JavaScript Document createElementNS() Method

What You’ll Learn

document.createElementNS() is an instance method that creates a new element with an explicit namespace URI and qualified name (see MDN Document: createElementNS()). Learn when you need it for SVG and MathML, how it differs from createElement(), common namespace strings, and five try-it labs.

Introduction

HTML pages often mix languages: HTML for layout, SVG for icons and charts, MathML for equations. Each language lives in its own namespace — a URI that tells the browser which vocabulary a tag belongs to.

document.createElementNS(namespaceURI, qualifiedName) creates an element in a chosen namespace. MDN notes this is useful when the parser cannot reliably infer the namespace — for example building SVG from JavaScript inside an HTML document.

For plain HTML tags (div, button, p), prefer the simpler createElement().

Related tutorials: createElement(), createAttributeNS(), appendChild().

Understanding document.createElementNS()

An instance method on the page’s document object (MDN Document interface).

• namespaceURI — string identifying the element vocabulary (SVG, MathML, XHTML, …).
• qualifiedName — localName or prefix:localName; initializes nodeName (MDN).
• Return value — a new Element in that namespace (MDN).
• Detached — still must be appended or inserted to appear on the page.
• Options — optional is / customElementRegistry (same rules as createElement; MDN).
• HTML shortcut — XHTML div via createElementNS is equivalent to createElement("div") (MDN).

📝 Syntax

General forms of Document.createElementNS (MDN):

createElementNS(namespaceURI, qualifiedName)
createElementNS(namespaceURI, qualifiedName, options)

Parameters

• namespaceURI — namespace string to associate with the element. Important values (MDN):
  • XHTML — http://www.w3.org/1999/xhtml
  • SVG — http://www.w3.org/2000/svg
  • MathML — http://www.w3.org/1998/Math/MathML
• qualifiedName — prefix:localName or localName. If prefix is xml or xmlns, the namespace URI must match the XML/xmlns namespaces (MDN).
• options (optional) — object with is or customElementRegistry (only one may be set; MDN). Some browsers also accept a string for backward compatibility.

Return value

The new Element (MDN).

Exceptions

• NamespaceError — invalid namespaceURI, empty URI with a prefix, or wrong URI for xml/xmlns prefixes (MDN).
• InvalidCharacterError — prefix or localName is not a valid name (MDN).
• NotSupportedError — both is and customElementRegistry are specified (MDN).

MDN XHTML equivalence

const divElementXHTML = document.createElementNS(
  "http://www.w3.org/1999/xhtml",
  "div",
);

// Equivalent for plain HTML:
const divElementHTML = document.createElement("div");

🌐 Common namespace URIs

Keep these strings in constants so you do not mistype them.

⚖️ createElementNS vs related APIs

Examples Gallery

Examples follow MDN Document: createElementNS() and practical SVG patterns beginners need first.

const xhtmlNS = "http://www.w3.org/1999/xhtml";

const divNS = document.createElementNS(xhtmlNS, "div");
const divHTML = document.createElement("div");

console.log(divNS.namespaceURI);  // "http://www.w3.org/1999/xhtml"
console.log(divHTML.namespaceURI); // "http://www.w3.org/1999/xhtml"
console.log(divNS instanceof HTMLDivElement); // true

http://www.w3.org/1999/xhtml
http://www.w3.org/1999/xhtml
true

const svgNS = "http://www.w3.org/2000/svg";

const svg = document.createElementNS(svgNS, "svg");
svg.setAttribute("width", "100");
svg.setAttribute("height", "100");

const circle = document.createElementNS(svgNS, "circle");
circle.setAttribute("cx", "50");
circle.setAttribute("cy", "50");
circle.setAttribute("r", "40");
circle.setAttribute("fill", "steelblue");

svg.appendChild(circle);
document.body.appendChild(svg);

console.log(svg instanceof SVGSVGElement);       // true
console.log(circle instanceof SVGCircleElement); // true

true
true
(a steelblue circle appears in a 100×100 SVG)

const wrong = document.createElement("svg");
const right = document.createElementNS("http://www.w3.org/2000/svg", "svg");

console.log(wrong instanceof HTMLUnknownElement); // true
console.log(wrong instanceof SVGSVGElement);      // false
console.log(right instanceof SVGSVGElement);      // true
console.log(wrong.namespaceURI); // "http://www.w3.org/1999/xhtml"
console.log(right.namespaceURI); // "http://www.w3.org/2000/svg"

true
false
true
http://www.w3.org/1999/xhtml
http://www.w3.org/2000/svg

const svgNS = "http://www.w3.org/2000/svg";
const path = document.createElementNS(svgNS, "path");

console.log({
  namespaceURI: path.namespaceURI,
  localName: path.localName,
  prefix: path.prefix,
  nodeName: path.nodeName,
  tagName: path.tagName
});

{
  namespaceURI: "http://www.w3.org/2000/svg",
  localName: "path",
  prefix: null,
  nodeName: "path",
  tagName: "path"
}

const mathNS = "http://www.w3.org/1998/Math/MathML";

const math = document.createElementNS(mathNS, "math");
const mi = document.createElementNS(mathNS, "mi");
mi.textContent = "x";
math.appendChild(mi);

document.body.appendChild(math);
console.log(math.namespaceURI);
console.log(math.outerHTML);
// <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>

http://www.w3.org/1998/Math/MathML
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>

🚀 Common Use Cases

• Dynamic SVG charts — build svg, path, and circle nodes from data.
• Icons in JS — assemble small SVG icons without innerHTML.
• MathML UIs — create equation markup programmatically.
• Mixed documents — when HTML embeds other vocabularies (MDN).
• Not for plain HTML — use createElement() for div, button, lists, etc.
• Namespaced attributes — pair with createAttributeNS / setAttributeNS when needed.

📝 Notes

• MDN: Baseline Widely available since July 2015 (* some parts may vary).
• Use createElementNS for SVG/MathML; use createElement for plain HTML (MDN).
• createElement("svg") in HTML yields HTMLUnknownElement and will not render SVG (MDN).
• Invalid namespace or name values throw (MDN: NamespaceError / InvalidCharacterError).
• Do not set both is and customElementRegistry (MDN).
• Store namespace URIs in constants to avoid typos.
• Related: createElement(), createAttributeNS(), appendChild().

💡 Best Practices