Document: createElement() method
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
* Some parts of this feature may have varying levels of support.
In anHTML document, thedocument.createElement() method creates the HTML element specified bylocalName, or anHTMLUnknownElement iflocalName isn't recognized.
Syntax
createElement(localName)createElement(localName, options)Parameters
localNameA 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()convertslocalNameto lower case before creating the element. In Firefox, Opera, and Chrome,createElement(null)works likecreateElement("null").optionsOptionalAn object with the following properties:
isThe tag name of a custom element previously defined via
customElements.define().SeeWeb component example for more details.
Return value
The newElement.
Note:A newHTMLElement is returned if the document is anHTMLDocument, which is the most common case. Otherwise a newElement is returned.
Examples
Basic example
This creates a new<div> and inserts it before the element with the IDdiv1.
HTML
<!doctype html><html lang="en-US"> <head> <meta charset="UTF-8" /> <title>Working with elements</title> </head> <body> <div>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
Note:Check thebrowser compatibility section for support, and theis attribute reference for caveats on implementation reality of customized built-in elements.
The following example snippet is taken from ourexpanding-list-web-component example (see it live also). In this case, our custom element extends theHTMLUListElement, which represents the<ul> element.
// Create a class for the elementclass ExpandingList extends HTMLUListElement { constructor() { // Always call super first in constructor super(); // constructor definition left out for brevity // … }}// Define the new elementcustomElements.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 anis 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
| Specification |
|---|
| DOM # ref-for-dom-document-createelement① |
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.