JavaScript Element getElementsByTagName() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word GETELEMENTSBYTAGNAME

Definition

In JavaScript, the getElementsByTagName() method returns a live HTMLCollection of every descendant with the given tag name (MDN). The element you call it on is not included — only its descendants.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call el.getElementsByTagName. Start with this line.

JavaScript
el.getElementsByTagName(tagName)
CallWhat it does
el.getElementsByTagName(tagName)Primary signature.
el.getElementsByTagName(...)Call with the arguments your case needs.

Built into the browser. Call getElementsByTagName(...) on an Element — no import required.

Library declarations
JavaScript
el.getElementsByTagName(tagName)

Parameters

This member has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*Live HTMLCollection

JavaScript Examples

Example 1 — Table Cells (MDN)

Collect every td under a table and read a data attribute.

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

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

How It Works

  1. Pick the table as root. Only descendants are searched.
  2. Pass "td". Every data cell under that table matches.
  3. Loop the collection. Order is document order (MDN).
  4. Read attributes. Useful for status checks without CSS selectors.

Example 2 — Wildcard "*"

Match every descendant element under a root.

JavaScript
const root = document.getElementById("box");
const all = root.getElementsByTagName("*");

console.log(all.length);
console.log(all[0].tagName);
Try It Yourself

How It Works

  1. Pass "*". MDN: represents all elements.
  2. Count descendants. Nested tags are included; the root is not.
  3. Read tagName. Useful when you need every element node under a container.
  4. Still live. Adding a child increases length automatically.

Example 3 — Live Collection

Length updates when you append another matching tag.

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

console.log(items.length); // before

const li = document.createElement("li");
li.textContent = "new";
root.appendChild(li);

console.log(items.length); // after — same collection, updated
Try It Yourself

How It Works

  1. Capture the collection once. No need to call the method again.
  2. Mutate the DOM. Append a new <li>.
  3. Length updates automatically. That is what “live” means (MDN).
  4. Contrast with querySelectorAll. A NodeList snapshot would stay at the old length.
Compatibility

Browser Support

Element.getElementsByTagName() is Baseline Widely available (MDN: across browsers since July 2015). Safe to use in modern evergreen browsers.

✓ Baseline · Widely available

getElementsByTagName()

Live HTMLCollection of descendant elements matching a tag name (or *).

99% Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
getElementsByTagName() Excellent

Bottom line: Use for fast tag lookups in a subtree; use getElementsByTagNameNS for SVG/XML namespaces, and querySelectorAll for CSS selectors or static lists.

Frequently Asked Questions

It returns a live HTMLCollection of descendant elements with the given tag name. The search is limited to the subtree of the element you call it on — not the element itself (MDN).
No. MDN marks Element.getElementsByTagName() as Baseline Widely available (across browsers since July 2015). It is not Deprecated, Experimental, or Non-standard.
A string with the qualified tag name to look for. The special string "*" returns all descendant elements. In HTML documents, the argument is lower-cased before searching (MDN).
getElementsByTagName() returns a live HTMLCollection that updates when the DOM changes. querySelectorAll() returns a static NodeList snapshot.
Yes. MDN: the list updates automatically with the DOM tree, so you do not need to call the method again after DOM changes.
In HTML documents, getElementsByTagName lower-cases the argument, which is undesirable for camel-cased SVG tags. Use getElementsByTagNameNS() to preserve capitalization (MDN).

Next: getElementsByTagNameNS()

Learn how to find elements by tag name within a namespace.

getElementsByTagNameNS tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Element getElementsByClassName() Method JavaScript Element getElementsByTagNameNS() Method