JavaScript Document createElement() Method

What You’ll Learn

document.createElement() is an instance method that creates a new element with the tag name you pass (see MDN Document: createElement()). Learn the lowercase HTML rule, how to set content and attributes, insert nodes with appendChild / insertBefore, the optional options object for customized built-ins, how it compares to createElementNS(), and five try-it labs.

Introduction

Static HTML is great for the first paint. Dynamic pages need JavaScript to build buttons, cards, list items, and alerts after the page loads.

document.createElement(localName) is the standard way to create those nodes. You get a real DOM element — not an HTML string — then set its text, attributes, and listeners before attaching it to the tree.

Prefer this over building markup with string concatenation and innerHTML when you control structure and text separately — it avoids accidental HTML injection and keeps nodes easy to update.

Related tutorials: createDocumentFragment(), appendChild(), createAttribute().

Understanding document.createElement()

An instance method on the page’s document object (MDN Document interface).

• Parameter — localName: tag name string (for example "div", "button").
• Return value — a new Element; on HTML documents usually an HTMLElement (MDN).
• Unknown tags — unrecognized names create an HTMLUnknownElement (MDN).
• HTML casing — on HTML documents, localName is lowercased before creation (MDN).
• Detached — the node is not in the page until you insert it.
• Options — optional object with is or customElementRegistry (not both) for custom elements (MDN).

📝 Syntax

General forms of Document.createElement (MDN):

createElement(localName)
createElement(localName, options)

Parameters

• localName — string for the element type. Do not use qualified names like "html:a" (MDN). On HTML documents the name is lowercased. In Firefox, Opera, and Chrome, createElement(null) behaves like createElement("null") (MDN).
• options (optional) — object. Only one of is or customElementRegistry may be set (MDN):
  • is — tag name of a customized built-in defined with customElements.define(..., { extends: "..." }); the element gets an is attribute.
  • customElementRegistry — a CustomElementRegistry for a scoped custom element registry.

Return value

The new Element. For an HTMLDocument (the common case), MDN: a new HTMLElement is returned.

Exceptions

• InvalidCharacterError — localName is not a valid element name (MDN).
• NotSupportedError — both is and customElementRegistry are specified (MDN).

MDN basic pattern

const newDiv = document.createElement("div");
const newContent = document.createTextNode("Hi there and greetings!");
newDiv.appendChild(newContent);

const currentDiv = document.getElementById("div1");
document.body.insertBefore(newDiv, currentDiv);

⚖️ createElement vs related APIs

Examples Gallery

Examples follow MDN Document: createElement() and everyday DOM patterns beginners use first.

function addElement() {
  const newDiv = document.createElement("div");
  const newContent = document.createTextNode("Hi there and greetings!");
  newDiv.appendChild(newContent);

  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

addElement();

Hi there and greetings!
(the new div appears above #div1)

const el = document.createElement("BUTTON");

console.log(el.tagName);   // "BUTTON" (DOM returns uppercase HTML tag names)
console.log(el.localName); // "button"
console.log(el instanceof HTMLButtonElement); // true

BUTTON
button
true

const btn = document.createElement("button");
btn.type = "button";
btn.className = "primary";
btn.textContent = "Save";
btn.addEventListener("click", () => {
  console.log("Saved!");
});

document.body.appendChild(btn);
console.log(btn.outerHTML);
// <button type="button" class="primary">Save</button>

<button type="button" class="primary">Save</button>
(clicking logs: Saved!)

const mystery = document.createElement("fancy-widget");

console.log(mystery.localName);                    // "fancy-widget"
console.log(mystery instanceof HTMLUnknownElement); // true
console.log(mystery instanceof HTMLElement);        // true

mystery.textContent = "Custom-looking tag";
document.body.appendChild(mystery);

fancy-widget
true
true

class ExpandingList extends HTMLUListElement {
  constructor() {
    super();
    // constructor body omitted for brevity
  }
}

customElements.define("expanding-list", ExpandingList, { extends: "ul" });

const expandingList = document.createElement("ul", { is: "expanding-list" });
console.log(expandingList.getAttribute("is")); // "expanding-list"
console.log(expandingList instanceof ExpandingList); // true where supported

expanding-list
true
(in browsers that support customized built-in elements)

🚀 Common Use Cases

• Dynamic UI — build cards, rows, toasts, and form controls from data.
• Safer text — pair with textContent instead of untrusted HTML strings.
• Event wiring — attach listeners on the element object before or after insert.
• Lists and tables — create many children, optionally via a DocumentFragment.
• Custom elements — create autonomous tags or customized built-ins (where supported).
• Not for SVG tags in HTML — use createElementNS for SVG/MathML namespaces.

📝 Notes

• MDN: Baseline Widely available since July 2015 (* some parts, like options, may vary).
• Do not pass qualified names such as "html:a" to createElement (MDN).
• Invalid localName values throw InvalidCharacterError (MDN).
• Setting both is and customElementRegistry throws NotSupportedError (MDN).
• Created nodes are detached until you insert them.
• For SVG or other namespaces, use document.createElementNS() (MDN See also).
• Related: appendChild(), createDocumentFragment(), createAttribute().

💡 Best Practices