Creating & changing elements

Build first, insert second

The previous DOM lessons taught you how to find existing nodes and read their text, HTML, attributes, and properties. This lesson is where the page starts changing shape. You will create brand-new elements, place them around existing ones, move them between parents, clone them, remove them, batch them in fragments, stamp them from templates, and insert trusted HTML strings at precise positions.

The most important mental model is simple: creating a node is not the same as inserting it. A new element can be configured safely while it is still off the page. Only an insertion method makes it part of the document tree that visitors see.

In the experiments below, every live DOM change happens inside an empty React ref container. React creates the empty box; the DOM APIs fill it. That keeps the demos safe next to React and mirrors how you might progressively enhance a small part of a page.

document.createElement("article") returns a new HTMLElement. It has no parent yet, so it is not visible. That off-page moment is useful: you can fill text with textContent, set attributes, append children, and only then insert the finished piece.

1const card = createElement("article");Run2const title = createElement("h3");3title.textContent = "DOM field note";4card.setAttribute("class", "note-card");5card.append(title);6console.log(card.outerHTML);

Notice that the replay is a small model, not a paused browser debugger. It records the same create → fill → attach order that the browser runs. The live playgrounds that follow verify the DOM behavior in your real browser.

Insertion methods answer two questions: inside or outside? and start or end? append and prepend insert children inside a parent. before and after insert siblings around the target itself.

1const list = document.querySelector("#planets");2const target = list.querySelector(".target");3const badge = document.createElement("li");4badge.textContent = "New moon";5 6list.append(badge);7list.prepend(badge);8target.before(badge);9target.after(badge);10target.replaceWith(badge);11list.insertAdjacentHTML("beforeend", "<li>HTML comet</li>");

The modern methods are flexible: append, prepend, before, after, and replaceWith accept any number of nodes and strings. Strings become Text nodes. They are never parsed as HTML. The older appendChild accepts one Node and returns it; the modern append returns undefined. The older insertBefore(newNode, referenceNode) inserts before a reference child, and referenceNode === null means append at the end.

A node has one parent. If it is already in the document and you insert it somewhere else, the browser moves it. Nothing is copied unless you ask for a clone.

1const inbox = document.querySelector("#inbox");2const done = document.querySelector("#done");3const task = inbox.querySelector("#task-1");4 5task.addEventListener("click", () => log("original clicked"));6 7// Move: the original leaves inbox and enters done.8done.append(task);9const shallow = task.cloneNode(false);10const deep = task.cloneNode(true);

Deep cloning has two surprises. First, listeners registered with addEventListener do not come along. Second, attributes do copy, including id. If you clone a card with id="profile-card", you now have duplicate IDs unless you fix them.

A DocumentFragment is a lightweight container for nodes. You can assemble many children in it, then append the fragment once. The fragment itself does not become a wrapper element. Its children move into the destination, leaving the fragment empty.

1const fragment = document.createDocumentFragment();2for (let i = 1; i <= 100; i += 1) {3  const item = document.createElement("li");4  item.textContent = "Row " + i;5  fragment.append(item);6}7list.append(fragment); // fragment.childNodes.length is now 08 9const copy = template.content.cloneNode(true);10copy.querySelector("h3").textContent = name;11cards.append(copy);

Sometimes you intentionally have a trusted HTML string, such as markup generated by your own code. insertAdjacentHTML(position, html) parses that string at one of four positions: beforebegin, afterbegin, beforeend, or afterend. It does not replace existing siblings or children outside the insertion point.

1const panel = document.querySelector(".panel");2const input = panel.querySelector("input");3input.value = "typed text";4 5// Safer for trusted markup: does not replace existing nodes.6panel.insertAdjacentHTML("beforeend", "<p>Added</p>");7// Avoid this pattern for adding: it reparses children.8panel.innerHTML += "<p>Added</p>";

There are two related methods with the same four positions: insertAdjacentElement(position, element) inserts an element node, and insertAdjacentText(position, text) inserts text without parsing HTML. To clear or replace all children in one readable operation, use replaceChildren().

container.append("<b>hi</b>");
container.appendChild(document.createElement("b"));
target.before("label", icon);
list.insertBefore(item, null);
panel.insertAdjacentHTML("beforeend", "<b>hi</b>");
box.textContent = "<b>hi</b>";
oldCard.replaceWith(newCard, " saved");

Where you will use this

You will use these APIs any time a page needs to render data without a full refresh: search results, todo lists, validation messages, notifications, empty states, and small widgets on server-rendered pages. Frameworks like React usually generate and update DOM nodes for you, but knowing the underlying operations makes debugging much easier.

function renderTodos(todos) {
  const list = document.createElement("ul");

  for (const todo of todos) {
    const item = document.createElement("li");
    item.textContent = todo.title;
    if (todo.done) item.setAttribute("data-done", "true");
    list.append(item);
  }

  app.replaceChildren(list);
}

This function creates a fresh list, fills each li with safe text, then uses replaceChildren to swap the app’s children in one step. If the list had old loading text, it disappears. If no arguments are passed, app.replaceChildren() simply clears the container.

Common misconceptions

• “createElement shows it immediately.” No. Creation makes a loose node. Insertion makes it visible.
• “append copies existing nodes.” No. Existing nodes move because a node has one parent.
• “append parses HTML strings.” No. Strings become Text nodes. Use HTML parsing APIs only for trusted markup.
• “cloneNode(true) copies everything.” It copies attributes and descendants, not listeners added with addEventListener or most JavaScript state.
• “A fragment remains as a wrapper.” No. Inserting a fragment moves its children and leaves it empty.
• “innerHTML += is just append for HTML.” It reparses and replaces children, which can disturb input state and listeners.

Key takeaways

• createElement creates a loose element; insertion methods attach it to the document.
• append, prepend, before, after, and replaceWith accept nodes and strings; strings become Text nodes.
• Inserting an existing node moves it. Use cloneNode for copies, then fix duplicate IDs and reattach JavaScript listeners.
• DocumentFragment batches children and empties when inserted. template.content is an inert fragment you clone.
• insertAdjacentHTML parses trusted HTML at a precise position. Use textContent for untrusted text.

Final definition: DOM modification is the art of creating or finding nodes, filling them safely, and deliberately moving, copying, replacing, or removing them in the document tree.

Up next: Styles & classes.