W3cubDocs

/Web APIs

Document: createElement() method

In an HTML document, the document.createElement() method creates the HTML element specified by tagName, or an HTMLUnknownElement if tagName isn't recognized.

Syntax

js

createElement(tagName)
createElement(tagName, options)

Parameters

tagName

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

options Optional

An object with the following properties:

is

The tag name of a custom element previously defined via customElements.define(). See Web component example for more details.

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.

Examples

Basic example

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

HTML

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

js

document.body.onload = addElement;

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);
}

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.

js

// 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:

js

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 with previous versions of the Custom Elements specification, 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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
createElement 1 12
1Doesn't conform to the DOM spec for XUL and XHTML documents: localName and namespaceURI are not set to null on the created element.
5 6 1 4.4 18 4 10.1 1 1.0
options_parameter
56For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
79For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
50Firefox accepts a string instead of an object here, but only from version 51 onwards. In version 50, options must be an object.
No
43For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
No
56For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
56For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
50Firefox accepts a string instead of an object here, but only from version 51 onwards. In version 50, options must be an object.
43For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.
No
6.0For backwards compatibility, the options parameter can be an object or a string with the custom element tag name, although the string version is deprecated.

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement