JavaScript Element getElementsByTagName() Method

What You’ll Learn

Element.getElementsByTagName() is an instance method that finds descendant elements by tag name and returns a live HTMLCollection. Learn table cell lookups, the "*" wildcard, comparison with getElementsByClassName() and querySelectorAll(), and five try-it labs aligned with MDN.

Introduction

Before querySelectorAll was everywhere, getElementsByTagName() was the standard way to grab every <p>, <li>, or <td> inside a section of the page. It still works well for simple tag-based lookups scoped to a parent element.

The return value is a live HTMLCollection. MDN notes it updates automatically when the DOM changes, so you usually do not need to call the method again after each mutation.

This page is part of JavaScript Element. Document.getElementsByTagName() works the same way from the document root (MDN).

Understanding the getElementsByTagName() Method

Calling el.getElementsByTagName(tagName) walks the subtree under el and collects every descendant whose tag name matches.

• It is an instance method on Element.
• tagName — the qualified name to look for; use "*" for all (MDN).
• Returns a live HTMLCollection in document order.
• Searches descendants only—not the element itself.
• In HTML, tag names are lower-cased before matching (MDN).
• Also available on Document for whole-page searches (MDN).

📝 Syntax

General form of Element.getElementsByTagName (MDN):

getElementsByTagName(tagName)

Parameters

tagName — a string with the qualified name to look for. The special string "*" matches all descendant elements (MDN).

Return value

A live HTMLCollection of matching elements in document order. Returns an empty collection when nothing matches (MDN).

Common patterns

// All paragraphs in a section
const paragraphs = section.getElementsByTagName("p");

// Table cells (MDN example)
const table = document.getElementById("forecast-table");
const cells = table.getElementsByTagName("td");

// Every descendant
const all = container.getElementsByTagName("*");

console.log(paragraphs.length);
console.log(cells[0]);

Examples Gallery

Examples follow MDN Element.getElementsByTagName() patterns. Use View Output or Try It Yourself for each case.

const table = document.getElementById("forecast-table");
const cells = table.getElementsByTagName("td");

for (const cell of cells) {
  const status = cell.getAttribute("data-status");
  console.log(status);
}

open
closed
open
open

const article = document.getElementById("article");
const paragraphs = article.getElementsByTagName("p");

console.log(paragraphs.length);
console.log(paragraphs[0].textContent);

2
First paragraph

const container = document.getElementById("widget");
const all = container.getElementsByTagName("*");

console.log(all.length);
// Every descendant tag inside #widget

6
(all descendant nodes)

const list = document.getElementById("list");
const items = list.getElementsByTagName("li");

console.log(items.length); // e.g. 2

const newItem = document.createElement("li");
newItem.textContent = "New";
list.appendChild(newItem);

console.log(items.length); // 3 — same collection, updated

2
3

const box = document.getElementById("box");

const byTag = box.getElementsByTagName("span");
const byQuery = box.querySelectorAll("span");

box.insertAdjacentHTML("beforeend", "Added");

console.log(byTag.length);    // increased
console.log(byQuery.length);  // unchanged snapshot

3
2
(live vs snapshot)

🚀 Common Use Cases

• Reading every <td> or <th> in a data table.
• Collecting all <li> items inside a list component.
• Iterating over <option> elements in a custom select widget.
• Counting descendant nodes with the "*" wildcard.
• Legacy scripts that rely on live HTMLCollections.
• Teaching the difference between tag, class, and selector-based lookups.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, July 2015).
• Returns a live HTMLCollection, not a static snapshot.
• Use "*" to match all descendant elements (MDN).
• In HTML documents, tag names are lower-cased before searching (MDN).
• For camel-cased SVG tags in HTML, use getElementsByTagNameNS() (MDN).
• Related: getElementsByClassName(), closest(), JavaScript hub.

💡 Best Practices