Walking & searching the DOM

Find your place in the tree

The browser turns your HTML into a tree of objects. This tree is called the DOM. Each object in the tree is a node. Once your code holds one node, it can reach other nodes in two ways:

• Walk. Follow a link from the node you have: "go to my parent", "go to my first child", or "go to the next sibling". A sibling is a node with the same parent.
• Search. Describe what you want with a CSS selector, such as li or .done, and let the browser find it. You can ask for the first match or for every match.

This lesson builds on The browser environment and The DOM tree. Here you move around the tree on purpose. For example, you go from a clicked button up to its card, or from a menu down to its items.

One difference trips up many people: elements versus nodes.

• An element is a tag, such as ul or li.
• A node is anything in the tree. That includes elements, but also text and comments. Even the spaces and line breaks between your tags become text nodes. We call these blank ones whitespace text nodes.

The property name tells you which kind you get. Names with Element in them, and children, give only elements. childNodes and firstChild give every kind of node.

Family links are the quickest way to move when the node you want is close by. The browser already keeps these links in the tree. So it just follows one link. It does not have to read a selector.

How to read this table: each row is one direction. The middle column skips text and comments. The last column includes them.

The top of the tree has a surprise. document.documentElement is the html element. Its parent is the document object. The document is a node, but it is not an element. So:

• parentNode of html is the document.
• parentElement of html is null, because there is no parent element.

const html = document.documentElement;
console.log(html.parentElement === null);
console.log(html.parentNode === document);

Line 1 saves the html element in html. Line 2 prints true: it has no parent element. Line 3 prints true: its parent node is the document.

The same thing happens at every dead end. The last child has no next sibling, so nextElementSibling gives null. Check for null before you read a property from the result.

1const list = menu;Run2let current = list.firstElementChild;3current = current.nextElementSibling;4current = current.parentElement;5console.log(current.id);

Now walk real nodes in your browser. The buttons with Element in their names skip whitespace text nodes. The other buttons can land on one, because the mini page has line breaks and spaces between its tags.

1const list = document.querySelector("#menu");2let current = list.firstElementChild;3current = current.nextElementSibling;4current = current.parentElement;5current = current.parentNode;6current = current.firstChild;7current = current.nextSibling;

When the node you want is not close by, search for it with a CSS selector. A selector is the pattern CSS uses to pick elements:

• li picks every li tag.
• .done picks every element with the class done.
• #menu picks the element with the id menu.

There are two search methods:

• querySelector(selector) gives the first matching element. If nothing matches, it gives null.
• querySelectorAll(selector) gives every matching element in a list called a NodeList. This list has a forEach method. It is static: it is a snapshot, so it does not change when the page changes later.

You can call both methods on document or on one element. On an element, the search only gives back elements inside it. These are its descendants: its children, their children, and so on.

But the selector itself still looks at the whole page. So menu.querySelectorAll("div p") can match a p inside menu even when the div is outside menu.

To mean "the element I called this on", write :scope. For example, :scope > li means li elements whose parent is that element.

1const menu = document.querySelector("#menu");2const firstDone = menu.querySelector(".done");3const allItems = menu.querySelectorAll("li");4const directItems = menu.querySelectorAll(":scope > li");5const dataItems = menu.querySelectorAll("[data-id]");

const missing = document.querySelector("#missing");
const noItems = document.querySelectorAll("#missing");
console.log(missing === null);
console.log(noItems.length);
try {
  document.querySelector("li[");
} catch (error) {
  console.log(error.name);
}

The page has no element with the id missing.

• Line 3 prints true. A good selector with no match gives null.
• Line 4 prints 0. The list from querySelectorAll is empty.
• Line 6 uses a broken selector, li[, with no closing bracket. The browser throws an error instead of giving an empty result. try and catch catch the error, and line 8 prints its name: SyntaxError.

Every element has two more selector methods:

• matches(selector) asks one yes-or-no question: does this exact element match? It gives true or false.
• closest(selector) checks the element itself first. If that doesn't match, it checks the parent, then the grandparent, and so on up the tree. It gives the first element that matches. If none match, it gives null.

This is very useful for event delegation. That means you put one click listener on a big container, instead of one listener on every button. Inside the listener, event.target is the exact element the click landed on. It might be an icon, a span, or the text inside a button. So you start from event.target and climb with closest to the button or card you care about.

1button.addEventListener("click", (event) => {2  const element = event.target;3  const isItem = element.matches("li");4  const row = element.closest("li");5  const menu = element.closest("#menu");6});

Sometimes you also need to check that one element is inside another. a.contains(b) gives true when b is a itself or is somewhere inside a.

const card = document.querySelector("[data-card-id]");
const button = document.querySelector("#menu button");
console.log(card.contains(button));
console.log(button.contains(card));
console.log(document.contains(card));

• Line 1 finds the card: the element with a data-card-id attribute. Line 2 finds the first button in the menu.
• Line 3 prints true. The button is inside the card.
• Line 4 prints false. The card is not inside the button. The order of the two matters.
• Line 5 prints true. The card is on the page, so the document contains it.

Use contains when an element you found must belong to the part of the page you meant.

Older search methods: getElementsBy*

Before querySelector existed, browsers had methods such as getElementsByTagName and getElementsByClassName. They still work, and you will see them in older code.

The big difference is not how you describe what to find. It is the kind of list you get back. These methods give an HTMLCollection. That is a list of elements that is live: it updates by itself when the page changes.

How to read this table: each row is one search method. The last column says whether its result changes after you get it.

You can loop over an HTMLCollection with for...of. But it has no forEach, map, or filter, because it is not an array. Array.from(collection) copies it into a real array. Use that when you want array methods, or a copy that won't change.

Live lists are handy, but they cause a bug when you remove items while you loop forward. Here is what happens with three items:

1. The loop starts at index 0 and removes the first item.
2. The live list updates. The old second item slides down to index 0.
3. The loop moves on to index 1. It never looks at index 0 again, so it skips the item that slid down.

Three safe fixes:

• Copy the list first with Array.from(live), then loop over the copy.
• Use querySelectorAll, which gives a snapshot.
• Loop backward, from the last index to 0.

1const liveItems = menu.getElementsByTagName("li");2const staticItems = menu.querySelectorAll("li");3menu.append(document.createElement("li"));4console.log(liveItems.length);5console.log(staticItems.length);6 7for (const item of liveItems) {8  item.remove();9}

const live = menu.getElementsByTagName("li");
const snapshot = menu.querySelectorAll("li");
menu.firstElementChild.remove();
console.log(live.length);
console.log(snapshot.length);

The menu starts with three li items. Line 1 gets a live list of them. Line 2 gets a snapshot of them. Line 3 removes the first item from the page.

• Line 4 prints 2. The live list followed the page.
• Line 5 prints 3. The snapshot still holds the three items it saw on line 2.

So a saved live list always shows the page as it is now. A saved snapshot can fall behind the page.

Where you’ll use this

Real pages often start from the small element that was clicked. Then the code needs the bigger part of the page around it. For example:

• In a to-do app, you click a delete icon. The code finds the to-do row around it.
• In a menu, you click a span inside a button. The code finds the button.
• In a product grid, you click "Save". The code finds the product card and reads its id.

The helper below does that last job. It uses three tools you may not know yet:

• button.dataset.action reads the data-action attribute from the HTML.
• card?.dataset uses ?. (optional chaining). If card is null, it stops and gives undefined instead of throwing an error.
• ?? null means "if the left side is null or undefined, use null instead".

1function findCardAction(event) {2  const button = event.target.closest("button[data-action]");3  if (!button) return null;4 5  const card = button.closest("[data-card-id]");6  return {7    action: button.dataset.action,8    cardId: card?.dataset.cardId ?? null,9  };10}

Line 1 takes the click event. Line 2 climbs from the clicked element to a button with a data-action attribute. Line 3 stops early with null when the click was not on such a button. Line 5 climbs again, to the card. Lines 6 to 9 give back the action and the card id.

This helper keeps working even if the button later gets an icon or an extra wrapper inside it. closest still climbs to the right button.

Tables have their own family links. A table element has rows and tBodies (its body sections), and each row has cells.

const table = document.querySelector("#orders");
console.log(table.rows.length);
console.log(table.rows[0].cells.length);
console.log(table.tBodies[0].rows[1].cells[0].textContent);

• Line 2 prints 3. rows holds the header row and the two body rows.
• Line 3 prints 2. The first row has two cells.
• Line 4 prints Toast. It takes the first body section, then its second row, then that row's first cell. You don't need a long selector for this.

Common misconceptions

• "A child is always an element." Not always. firstChild can be a whitespace text node. Use firstElementChild to get a tag.
• "A search with no match throws an error." No. A good selector with no match gives null or an empty list. Only a broken selector throws a SyntaxError.
• "A NodeList is always static." No. querySelectorAll gives a static NodeList, but childNodes is a live NodeList.
• "An HTMLCollection is an array." No. You can loop over it with for...of, but it has no array methods such as forEach.
• "closest searches inside the element." No. It checks the element itself, then goes up through its parents. It never looks down.
• "A search on an element only reads that element." No. The selector still looks at the whole page. Use :scope when the selector must start at the element you called it on.

Key takeaways

• Use the properties with Element in their names (and children) when you want tags, not whitespace text nodes.
• querySelector gives the first match or null. querySelectorAll gives a static NodeList of every match.
• matches asks about one element. closest checks that element, then each parent going up.
• getElementsByTagName, getElementsByClassName, and children give live lists that update by themselves.
• Before you remove items from a live list in a loop, copy it with Array.from, or loop backward.

DOM navigation is picking the right path through the page tree: follow family links when the node is close by, and search with a selector when you need to find matches.

Up next: Node properties & contents.