Creating & changing elements

Build first, insert second

The DOM is the tree of objects the browser builds from a page's HTML. Each part of the tree is a node: an element such as a paragraph, or a piece of text. In the last few lessons you found nodes and read their text and attributes. In this lesson you change the page.

You will learn to:

• make new elements;
• put them on the page, in the exact spot you want;
• move, copy, replace, and remove them;
• build many at once, with a fragment or a template;
• add HTML from a string, and know when that is not safe.

One rule matters most: making an element does not put it on the page. A new element sits on its own until you insert it. While it waits, you can give it text and attributes. Then one method call puts it on the page.

The experiments below change a real page. Each one works inside an empty box on this page. React, the tool that builds this site, makes the empty box. The DOM methods from this lesson fill it. That way your changes never break the rest of the page.

document.createElement("article") makes a new <article> element and gives it back to you. The new element has no parent yet. A parent is the element that holds another element. With no parent, the element is not on the page, so nobody can see it.

That is a good moment to get it ready. You can:

• set its text with textContent;
• set attributes, such as class;
• put other elements inside it.

Then you insert the finished element. Step through the code below to see each step. Here createElement is a short name for document.createElement.

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

This replay is a small copy of what the browser does. It is not the browser itself. It shows the same order: make, fill, then join. The experiments later in this lesson run the real methods in your browser.

Text can be a node of its own, too. The next example makes one on purpose.

const item = document.createElement("li");
const label = document.createTextNode("Buy tea");
item.appendChild(label);
list.appendChild(item);
console.log(item.textContent);

• Line 1 makes an empty list item, item.
• Line 2 makes a text node: a node that holds only the text Buy tea.
• Line 3 puts the text node inside item with appendChild.
• Line 4 puts item at the end of a list that is already on the page.
• Line 5 prints Buy tea.

appendChild takes exactly one node. It gives back the node it added. It never reads a string as HTML.

Each row of this table is one way to fill a new element. The middle column says whether the browser reads tags such as <b> in your string as real HTML.

Four methods put a node next to a target, the element you call the method on. Each method answers two questions: inside the target or outside it? At the start or at the end?

• append puts the node inside the target, as its last child.
• prepend puts the node inside the target, as its first child.
• before puts the node outside, just before the target.
• after puts the node outside, just after the target.

A child is a node inside another node. A sibling is a node next to it, with the same parent. So append and prepend add children, and before and after add siblings. Try each button below and watch where the new item lands.

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

These methods are flexible. append, prepend, before, after, and replaceWith all take as many nodes and strings as you like. Each string becomes a text node. It is never read as HTML.

Two older methods do similar jobs:

• appendChild(node) takes exactly one node and gives it back. The newer append gives back undefined.
• insertBefore(newNode, referenceNode) puts newNode just before the child referenceNode. If referenceNode is null, it puts the new node at the end.

What if the node is already on the page, in another list? The next example tries it.

const inbox = document.createElement("ul");
const done = document.createElement("ul");
const task = document.createElement("li");
task.textContent = "Email Sam";
inbox.appendChild(task);
done.appendChild(task);
console.log(inbox.children.length + "|" + done.textContent);

Line 5 puts the task into inbox. Line 6 puts the same task into done. The task does not get copied. It moves, so inbox is left with 0 children. The code prints 0|Email Sam.

If both lists need the task, make a copy with cloneNode. You will see how in the next section.

A node can have only one parent. Say a node is already on the page, and you insert it somewhere else. The browser takes it out of its old place and puts it in the new one. That is a move. Nothing gets copied unless you ask for a copy.

To make a copy, call cloneNode. A copy is also called a clone. In the experiment below, a task has a click listener: a function that runs when you click it. You add a listener with addEventListener. Move the task, make copies, and click each one.

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

Each row of this table is one job. Find the job you want, then read which method does it.

A deep copy, made with cloneNode(true), has two surprises:

• Listeners added with addEventListener are not copied.
• Attributes are copied, and that includes id. An id should be used only once on a page. If you copy a card with id="profile-card", two elements now have the same id. Change the copy's id before you use it.

const oldMessage = document.createElement("p");
oldMessage.textContent = "Loading...";
app.replaceChildren(oldMessage);
const readyMessage = document.createElement("p");
readyMessage.textContent = "Ready";
oldMessage.replaceWith(readyMessage);
readyMessage.remove();
console.log(app.children.length);

• Line 3 uses replaceChildren to put the Loading... paragraph inside app.
• Line 6 uses replaceWith to swap that paragraph for the Ready paragraph.
• Line 7 uses remove to take the Ready paragraph off the page.
• Line 8 prints 0, because app has no children left.

These methods really change the tree. They do not just hide an element with CSS.

const original = document.createElement("article");
original.id = "profile";
const name = document.createElement("h2");
name.textContent = "Asha";
original.append(name);
original.addEventListener("click", () => console.log("clicked"));
const copy = original.cloneNode(true);
copy.id = "profile-copy";
console.log(copy.id + "|" + copy.textContent + "|" + (copy.children.length === 1));

• Lines 1 to 5 make an article with the id profile and a heading, Asha.
• Line 6 adds a click listener to the original.
• Line 7 makes a deep copy. The copy gets the heading and the id profile.
• Line 8 changes the copy's id to profile-copy, so the id is not used twice.
• Line 9 prints profile-copy|Asha|true.

The copy did not get the click listener from line 6. If the copy needs to react to clicks, add a new listener to it.

A DocumentFragment is a light holder for nodes. It is never shown on the page. You use it like this:

1. Make a fragment with document.createDocumentFragment().
2. Put many nodes into the fragment, one by one.
3. Append the fragment to the page, once.

The fragment itself is not added to the page. Only its children are. They move out of the fragment, so the fragment is empty afterwards.

A <template> element holds HTML that the browser does not use yet. Images inside it do not load. Scripts inside it do not run. Its content property is a fragment with that HTML. You copy the content with cloneNode(true), fill in the copy, and insert it. You can do that as many times as you like.

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

const fragment = document.createDocumentFragment();
for (const title of ["Tea", "Bread"]) {
  const item = document.createElement("li");
  item.textContent = title;
  fragment.append(item);
}
list.append(fragment);
const card = template.content.cloneNode(true);
card.querySelector("h3").textContent = "Asha";
cards.append(card);
console.log(list.children.length + "|" + cards.querySelector("h3").textContent);

• Line 1 makes an empty fragment.
• Lines 2 to 6 make two list items, Tea and Bread, and put them in the fragment.
• Line 7 appends the fragment. Both items move into list, and the fragment is left empty.
• Line 8 copies the template's content.
• Line 9 sets the copied heading's text to Asha.
• Line 10 puts the copy into cards.
• Line 11 prints 2|Asha.

When should you use each one?

• Use a fragment when several new nodes belong to one change.
• Use a template when you add the same shape again and again, like one card per user.

Neither one makes text safe by itself. For text, still use textContent.

Sometimes you do want a string read as HTML. For example, your own code wrote the string, so you trust it. insertAdjacentHTML(position, html) reads the string as HTML and adds the new elements at one of four positions:

• beforebegin: outside, just before the element.
• afterbegin: inside, before its first child.
• beforeend: inside, after its last child.
• afterend: outside, just after the element.

It only adds. It leaves every node that is already there alone. Type in the box below, then compare it with innerHTML +=.

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>";

const button = document.createElement("button");
let clicks = 0;
button.addEventListener("click", () => { clicks += 1; });
panel.append(button);
panel.innerHTML += "<p>Added</p>";
panel.querySelector("button").click();
console.log(clicks);

• Line 3 adds a listener that adds 1 to clicks each time the button is clicked.
• Line 4 puts the button inside panel.
• Line 5 runs panel.innerHTML += "<p>Added</p>". This turns all of the panel's HTML into a string, adds the new part, and reads the whole string again. The browser throws away the old button and makes a new one. The new button has no listener.
• Line 6 clicks the new button. Nothing happens.
• Line 7 prints 0.

To add HTML you trust without rebuilding what is already there, use insertAdjacentHTML.

Two more methods use the same four positions:

• insertAdjacentElement(position, element) puts an element there.
• insertAdjacentText(position, text) puts text there. It never reads tags.

To remove all of an element's children, or swap them all for new ones in one step, use replaceChildren().

const message = document.createElement("p");
const userText = "<strong>Welcome</strong>";
message.textContent = userText;
app.append(message);
console.log(message.children.length + "|" + message.textContent);

The string on line 2 has tags in it. Line 3 puts it into the paragraph with textContent, which never reads tags. So the paragraph has no child elements. The page shows the angle brackets as plain characters. Line 5 prints 0|<strong>Welcome</strong>.

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

const note = document.createElement("p");
note.textContent = "Saved";
panel.insertAdjacentElement("beforebegin", note);
panel.insertAdjacentText("afterend", "End of panel");
console.log(note.textContent + "|" + panel.nextSibling.textContent);

• Lines 1 and 2 make a paragraph that says Saved.
• Line 3 puts the paragraph just before the panel, outside it.
• Line 4 puts the text End of panel just after the panel, outside it.
• Line 5 prints Saved|End of panel.

insertAdjacentElement takes an element node. insertAdjacentText makes a text node and never reads tags.

Where you will use this

You use these methods whenever a page shows new things without loading a whole new page. For example:

• search results;
• to-do lists;
• error messages under a form field;
• pop-up notices;
• a "nothing here yet" message when a list is empty.

Tools like React usually make and change DOM nodes for you. Knowing these methods still helps you understand what the tool does, and find bugs faster.

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

• Line 2 makes a new, empty list.
• Lines 4 to 9 make one li for each to-do, set its text with textContent, and add it to the list.
• Line 11 uses replaceChildren to swap everything inside app for the new list, in one step. Any old text, like a loading message, is gone.

If you call app.replaceChildren() with nothing in the brackets, it just empties app.

const list = document.createElement("ul");
function addTodo(title) {
  const item = document.createElement("li");
  item.textContent = title;
  list.append(item);
  return item;
}
addTodo("Read DOM lesson");
const extra = addTodo("Try cloneNode");
extra.remove();
app.replaceChildren(list);
console.log(list.textContent.trim());

• Lines 2 to 7 define addTodo. It makes one item, sets its text, adds it to the list, and gives the item back.
• Line 8 adds Read DOM lesson.
• Line 9 adds Try cloneNode and keeps the item in extra.
• Line 10 removes that second item.
• Line 11 puts the finished list into app.
• Line 12 prints Read DOM lesson.

This works well for a small part of a page. But if a tool like React looks after that same part, let the tool make the changes. Two things changing the same nodes will get in each other's way.

Common misconceptions

• "createElement puts the element on the page." No. It only makes the element. It shows up only after you insert it.
• "append copies a node that is already on the page." No. The node moves, because a node can have only one parent.
• "append reads a string as HTML." No. A string becomes a text node. Use the HTML methods only for HTML you trust.
• "cloneNode(true) copies everything." No. It copies attributes and children. It does not copy listeners added with addEventListener.
• "A fragment stays on the page around its children." No. Inserting a fragment moves its children out and leaves it empty.
• "innerHTML += just adds HTML at the end." No. It rebuilds all the children. Typed text and listeners on them can be lost.

Key takeaways

• createElement makes an element. It is not on the page until you insert it.
• append, prepend, before, after, and replaceWith take nodes and strings. A string becomes a text node.
• Inserting a node that is already on the page moves it. To copy it, use cloneNode. Then change any copied id, and add listeners again.
• A DocumentFragment holds many nodes, and is empty after you append it. template.content is a fragment you copy each time you need it.
• insertAdjacentHTML reads a string as HTML, at one of four positions. Use it only for HTML you trust. For text, use textContent.

In one sentence: to change the page, you make or find nodes, fill them with safe text, and then move, copy, replace, or remove them on purpose.

Up next: Styles & classes.