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

Note: In a XUL document, it creates the specified XUL element. In other documents, it creates an element with a null namespace URI.


var element = document.createElement(tagName[, options]);


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").
An optional ElementCreationOptions object containing a single property named is, whose value is the tag name for a custom element previously defined using customElements.define(). See Web component example for more details.

Return value

The new Element.


Basic example

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


<!DOCTYPE html>
  <title>||Working with elements||</title>
  <div id="div1">The text above has been created dynamically.</div>


document.body.onload = addElement;

function addElement () { 
  // create a new div element 
  var newDiv = document.createElement("div"); 
  // and give it some content 
  var newContent = document.createTextNode("Hi there and greetings!"); 
  // add the text node to the newly created div

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

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

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


Specification Status Comment
The definition of 'Document.createElement' in that specification.
Living Standard  

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 54 (Yes) (Yes)[1][2] (Yes) 41 (Yes)
options argument (Yes)[3] ? 50 (50)[4][5] ? (Yes)[3] ?
Feature Android Webview Chrome for Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 54 54 (Yes) (Yes) (Yes) 41 (Yes)
options argument (Yes)[3] (Yes)[3] ? ? ? (Yes)[3] ?

[1] Starting with Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19) createElement() no longer uses the HTMLSpanElement interface when the argument is "bgsounds", "multicol", or "image".  Instead, HTMLUnknownElement is used for "bgsound" and "multicol" and HTMLElement HTMLElement is used for "image".

[2] The Gecko implementation of createElement doesn't conform to the DOM spec for XUL and XHTML documents: localName and namespaceURI are not set to null on the created element. See bug 280692 for details.

[3] In previous versions of the specification, this argument was just a string whose value was the custom element's tag name. For example it could take document.createElement("button", "custom-button") rather than document.createElement("button", {is: "custom-button"}). For the sake of backwards compatibility, Chrome accepts both forms, though the string form is deprecated.

[4] See [3] above: like Chrome, Firefox accepts a string instead of an object here, but only from version 51 onwards. In version 50,  options must be an object.

[5] To experiment with custom elements in Firefox, you must set the dom.webcomponents.enabled and dom.webcomponents.customelements.enabled preferences to true.

Quantum CSS notes

  • In Gecko, when you create a detached subtree (e.g. a <div> created using createElement() that is not yet inserted into the DOM), the subtree's root element is set as a block-level element. In Firefox's new parallel CSS engine (also known as Quantum CSS or Stylo, planned for release in Firefox 57), this is set as inline, as per spec (bug 1374994).

See also