Document: createElementNS() method

Syntax

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

Parameters

namespaceURI

A string that specifies the namespaceURI to associate with the element. Some important namespace URIs are:

HTML

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

SVG

http://www.w3.org/2000/svg

MathML

http://www.w3.org/1998/Math/MathML

qualifiedName

A string containing the qualified name of the new element. The nodeName property of the created element is initialized with this value.

The format of the qualified name is prefix:localName or localName, where the parts are defined as:

prefix Optional

A "short alias" for the namespace. The prefix is optional, but if it is specified the namespaceURI parameter must also be specified. If the prefix is set to xml or xmlns, the namespaceURI must be set to http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/, respectively.

The value is used to initialize the new element's prefix property. If not set, its value is null.

localName:

The local name of the element. The value is used to initialize the new Element's localName property.

options Optional

An object with the following optional properties (note that only one of is and customElementRegistry may be set):

is Optional

A string defining the tag name for a custom element (that was previously defined using customElements.define()). The new element will be given an is attribute whose value is the custom element's tag name. See Web component example for more details.

customElementRegistry Optional

A CustomElementRegistry that sets the Scoped custom element registry of a custom element.

For backwards compatibility, some browsers allow you to pass a string here instead of an object, where the string's value is the custom element's tag name. See Extending native HTML elements for more information on how to use this parameter.

Return value

The new Element.

Exceptions

NamespaceError DOMException

Thrown if the namespaceURI value is:

• not a valid namespace URI
• set to the empty string when prefix has a value
• not the value http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/ when prefix is set to xml or xmlns, respectively.

InvalidCharacterError DOMException

Thrown if either the prefix or localName is not valid:

• The prefix must have at least one character, and cannot contain ASCII whitespace, NULL, / , or > (U+0000, U+002F, or U+003E, respectively).
• The localName is a valid element name if it has a length of at least 1 and:
  • it starts with an alphabet character and does not contain ASCII whitespace, NULL, / , or > (U+0000, U+002F, or U+003E, respectively).
  • it starts with : (U+003A ), _ (U+005F), or any characters in the range U+0080 to U+10FFFF (inclusive), AND the remaining code points only include those same characters along with the ASCII alphanumeric characters, - (U+002D), and . (U+002E),

Note: Earlier versions of the specification were more restrictive, requiring that the qualifiedName be a valid XML name.

NotSupportedError DOMException

Thrown if both the is and customElementRegistry options are specified.

Examples

Basic usage

This creates a new <div> element in the XHTML namespace and appends it to the vbox element. Although this is not an extremely useful XUL document, it does demonstrate the use of elements from two different namespaces within a single document:

<?xml version="1.0"?>
<page xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
      xmlns:html="http://www.w3.org/1999/xhtml"
      title="||Working with elements||"
      onload="init()">

<script><![CDATA[
let container;
let newDiv;
let textNode;

function init() {
  container = document.getElementById("ContainerBox");
  newDiv = document.createElementNS("http://www.w3.org/1999/xhtml", "div");
  textNode = document.createTextNode(
    "This is text that was constructed dynamically with createElementNS and createTextNode then inserted into the document using appendChild.",
  );
  newDiv.appendChild(textNode);
  container.appendChild(newDiv);
}
]]></script>

 <vbox id="ContainerBox" flex="1">
  <html:div>
   The script on this page will add dynamic content below:
  </html:div>
 </vbox>

</page>

Specifications

Browser compatibility

See also

• document.createElement()
• document.createTextNode()
• Element.namespaceURI