JavaScript Element getElementsByTagNameNS() Method

What You’ll Learn

Element.getElementsByTagNameNS() is an instance method that finds descendant elements by namespace URI and local name, returning a live HTMLCollection. Learn the XHTML and SVG namespaces, MDN’s table-cell pattern, the "*" wildcard, when to prefer this over getElementsByTagName(), and five try-it labs aligned with MDN.

Introduction

Most everyday HTML uses one namespace — the XHTML namespace (http://www.w3.org/1999/xhtml). When you embed SVG or MathML, elements belong to different namespaces. getElementsByTagNameNS() lets you search by both namespace URI and local name instead of a plain tag string.

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.getElementsByTagNameNS() works the same way from the document root (MDN).

Understanding the getElementsByTagNameNS() Method

Calling el.getElementsByTagNameNS(namespaceURI, localName) walks the subtree under el and collects every descendant whose namespace and local name match.

• It is an instance method on Element.
• namespaceURI — the namespace of elements to find (see Element.namespaceURI, MDN).
• localName — the local tag name, or "*" for all in that namespace (MDN).
• Returns a live HTMLCollection in document order.
• Searches descendants only—not the element itself.
• Common URI: http://www.w3.org/1999/xhtml for HTML/XHTML elements.
• Also available on Document for whole-page searches (MDN).

📝 Syntax

General form of Element.getElementsByTagNameNS (MDN):

getElementsByTagNameNS(namespaceURI, localName)

Parameters

namespaceURI — the namespace URI of elements to look for. For XHTML/HTML elements, use http://www.w3.org/1999/xhtml (MDN). For SVG, use http://www.w3.org/2000/svg.

localName — the local name of elements to look for, or the special value "*" which matches all elements in that namespace (MDN).

Return value

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

Common patterns

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const SVG_NS = "http://www.w3.org/2000/svg";

// XHTML paragraphs in a section
const paragraphs = section.getElementsByTagNameNS(XHTML_NS, "p");

// MDN table-cell pattern
const cells = table.getElementsByTagNameNS(XHTML_NS, "td");

// SVG circles inside an inline SVG root
const circles = svgRoot.getElementsByTagNameNS(SVG_NS, "circle");

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

Examples Gallery

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

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const table = document.getElementById("forecast-table");
const cells = table.getElementsByTagNameNS(XHTML_NS, "td");

for (const cell of cells) {
  if (cell.getAttribute("axis") === "year") {
    console.log(cell.textContent);
  }
}

2024
2025

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const article = document.getElementById("article");
const paragraphs = article.getElementsByTagNameNS(XHTML_NS, "p");

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

2
First paragraph

const SVG_NS = "http://www.w3.org/2000/svg";
const svgRoot = document.getElementById("chart");
const circles = svgRoot.getElementsByTagNameNS(SVG_NS, "circle");

console.log(circles.length);
console.log(circles[0].getAttribute("r"));

3
12

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const container = document.getElementById("widget");
const xhtmlNodes = container.getElementsByTagNameNS(XHTML_NS, "*");

console.log(xhtmlNodes.length);
// Every XHTML-namespace descendant inside #widget

5
(XHTML descendants only)

const SVG_NS = "http://www.w3.org/2000/svg";
const svg = document.getElementById("gradient-svg");

const byNS = svg.getElementsByTagNameNS(SVG_NS, "linearGradient");
const byTag = svg.getElementsByTagName("linearGradient");

console.log(byNS.length);  // finds camel-case SVG
console.log(byTag.length); // often 0 in HTML

1
0
(NS vs plain tag)

🚀 Common Use Cases

• Reading XHTML table cells in mixed or XML-style documents (MDN).
• Collecting SVG shapes like <circle> or <path> inside inline SVG.
• Finding camel-cased SVG elements such as linearGradient in HTML.
• Counting all descendants in one namespace with localName "*".
• Legacy XML tooling that relies on namespace-aware DOM walks.
• Teaching the difference between plain tag search and namespace URIs.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, July 2015).
• Returns a live HTMLCollection, not a static snapshot.
• Use "*" as localName to match all elements in a namespace (MDN).
• HTML elements use namespace http://www.w3.org/1999/xhtml (MDN).
• For camel-cased SVG in HTML, prefer this over getElementsByTagName() (MDN).
• Related: getElementsByTagName(), getAttributeNS(), JavaScript hub.

💡 Best Practices