Document: createElement() method

Syntax

createElement(localName)
createElement(localName, options)

Parameters

localName

A string that specifies the type of element to be created. Don't use qualified names (like "html:a") with this method. When called on an HTML document, createElement() converts localName to lowercase before creating the element. In Firefox, Opera, and Chrome, createElement(null) works like createElement("null").

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 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.

Return value

The new Element.

Exceptions

InvalidCharacterError DOMException

Thrown if the localName value is not a valid element name. A string is a valid element name if its length is 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 localName be a valid XML name.

NotSupportedError DOMException

Thrown if both the is and customElementRegistry options are specified.

Examples

Basic example

This creates a new <div> and inserts it before the element with the ID div1.

HTML

<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <title>Working with elements</title>
  </head>
  <body>
    <div id="div1">The text above has been created dynamically.</div>
  </body>
</html>

JavaScript

function addElement() {
  // create a new div element
  const newDiv = document.createElement("div");

  // and give it some content
  const newContent = document.createTextNode("Hi there and greetings!");

  // add the text node to the newly created div
  newDiv.appendChild(newContent);

  // add the newly created element and its content into the DOM
  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

addElement();

Result

Web component example

The following example snippet is taken from our expanding-list-web-component example (see it live also). In this case, our custom element extends the HTMLUListElement, which represents the <ul> element.

// Create a class for the element
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Always call super first in constructor
    super();

    // constructor definition left out for brevity
    // …
  }
}

// Define the new element
customElements.define("expanding-list", ExpandingList, { extends: "ul" });

If we wanted to create an instance of this element programmatically, we'd use a call along the following lines:

let expandingList = document.createElement("ul", { is: "expanding-list" });

The new element will be given an is attribute whose value is the custom element's tag name.

Specifications

Browser compatibility

See also

• Node.removeChild()
• Node.replaceChild()
• Node.appendChild()
• Node.insertBefore()
• Node.hasChildNodes()
• document.createElementNS() — to explicitly specify the namespace URI for the element.