web api instance method

Document: createElement() method

The createElement() method of the Document interface creates a new HTMLElement that has the specified localName.

If localName isn’t recognized, the method creates an HTMLUnknownElement.

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.

[!NOTE] A new HTMLElement is returned if the document is an HTMLDocument, which is the most common case. Otherwise a new Element is returned.

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

Interactive exampleOpen the canonical MDN source to run this embedded demo.

Web component example

[!NOTE] Check the browser compatibility section for support, and the is attribute reference for caveats on implementation reality of customized built-in elements.

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.

[!NOTE] For backwards compatibility, some browsers will allow you to pass a string here instead of an object, where the string’s value is the custom element’s tag name.

Specifications

SpecificationsStandards references are available on the canonical MDN page.

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.