JavaScript Document getElementsByTagNameNS() Method

What You’ll Learn

document.getElementsByTagNameNS() is an instance method that returns elements matching a namespace URI and a local tag name (see MDN Document: getElementsByTagNameNS()). Learn when to use it for SVG/HTML namespaces, how it differs from getElementsByTagName(), and five try-it labs.

Introduction

Regular HTML pages usually need only getElementsByTagName(). When SVG (or other namespaces) mix into the document, tag names alone may not be enough — you also need the namespace URI.

MDN: getElementsByTagNameNS returns a list of elements with the given tag name belonging to the given namespace. The complete document is searched, including the root node.

Related tutorials: getElementsByTagName(), getElementsByClassName(), getSelection().

Understanding document.getElementsByTagNameNS()

An instance method on the Document interface (MDN). The same API also exists on elements for scoped searches.

• namespace — the namespace URI of elements to look for (see element.namespaceURI) (MDN).
• name — local name to match, or * for all elements in that namespace (see element.localName) (MDN).
• Case-sensitive — unlike getElementsByTagName(), parameters are case-sensitive (MDN).
• Return value — a live HTMLCollection in tree order (MDN).
• Whole document — search includes the root node (MDN).
• Element scope — call on a parent to search only descendants (MDN).

📝 Syntax

General form of Document.getElementsByTagNameNS (MDN):

getElementsByTagNameNS(namespace, name)

Parameters

• namespace — the namespace URI of elements to look for (MDN).
• name — either the local name of elements to look for or the special value *, which matches all elements (MDN).

Return value

A live HTMLCollection of found elements in the order they appear in the tree (MDN).

MDN note on case

Unlike document.getElementsByTagName(), the parameters for getElementsByTagNameNS() are case-sensitive (MDN).

MDN quick sample

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const allParas = document.getElementsByTagNameNS(XHTML_NS, "p");
console.log(allParas.length);

⚖️ getElementsByTagNameNS vs getElementsByTagName

Examples Gallery

Examples follow MDN Document: getElementsByTagNameNS() and practical SVG/HTML patterns.

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const allParas = document.getElementsByTagNameNS(XHTML_NS, "p");
console.log(`There are ${allParas.length} <p> elements in this document`);

There are 8 <p> elements in this document
(depends on the page markup)

const XHTML_NS = "http://www.w3.org/1999/xhtml";
const div1 = document.getElementById("div1");
const div1Paras = div1.getElementsByTagNameNS(XHTML_NS, "p");
console.log(`There are ${div1Paras.length} <p> elements in div1 element`);

There are 5 <p> elements in div1 element

const SVG_NS = "http://www.w3.org/2000/svg";
const circles = document.getElementsByTagNameNS(SVG_NS, "circle");
console.log(circles.length);
if (circles[0]) {
  console.log(circles[0].getAttribute("r"));
}

2
40

const SVG_NS = "http://www.w3.org/2000/svg";
const svgNodes = document.getElementsByTagNameNS(SVG_NS, "*");
console.log(svgNodes.length);
for (const el of svgNodes) {
  console.log(el.localName);
}

3
svg
circle
circle

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

console.log("plain p:", document.getElementsByTagName("p").length);
console.log("NS p:", document.getElementsByTagNameNS(XHTML_NS, "p").length);
console.log("NS circle:", document.getElementsByTagNameNS(SVG_NS, "circle").length);

plain p: 2
NS p: 2
NS circle: 1

🚀 Common Use Cases

• SVG tooling — select circle, path, or text nodes precisely.
• Mixed documents — pages that embed SVG inside HTML.
• Case-sensitive names — avoid HTML lowercasing surprises (MDN).
• Scoped widgets — search only inside one container element.
• Namespace audits — list every node in the SVG namespace with *.
• Prefer plain tag lookup — for simple HTML-only pages, use getElementsByTagName().

📝 Notes

• MDN: Baseline Widely available since July 2015.
• MDN: returns a live HTMLCollection in tree order.
• MDN: parameters are case-sensitive (unlike getElementsByTagName).
• MDN: * matches all elements for the given namespace.
• Namespace URIs are identifiers, not pages you must download.
• Related: getElementsByTagName(), getElementsByClassName(), getSelection().

💡 Best Practices