The DOM tree

A page becomes a tree

A web page starts as HTML text. The text comes from a file or from a server. On its own, it is just letters and angle brackets.

The browser reads this text with its HTML parser. A parser is a program that reads text and works out its structure. From the text, the parser builds the DOM. DOM is short for Document Object Model.

The DOM is:

• a set of objects, one for each part of the page,
• arranged as a tree, where each object can hold other objects,
• live, so JavaScript can read it and change it while the page is open.

Each object in the tree is called a node. The node at the very top is called the root. On a web page, the root is document.

1document2├─ <!DOCTYPE html>3└─ HTML4   ├─ HEAD5   └─ BODY

Read this sketch from the top down:

1. Line 1 is document, the root.
2. Line 2 is the doctype, <!DOCTYPE html>. It sits right under document.
3. Line 3 is the <html> element. It also sits right under document.
4. Lines 4 and 5 are <head> and <body>. They sit inside <html>.

You don't have to search for these three elements. document has a property for each one:

• document.documentElement is the <html> element.
• document.head is the <head> element.
• document.body is the <body> element.

console.log(document.documentElement.nodeName);
console.log(document.head.nodeName);
console.log(document.body.nodeName);

nodeName is a property that gives a node's name. For an HTML element, the name is the tag name in capital letters. So line 1 prints HTML, line 2 prints HEAD, and line 3 prints BODY.

One warning about timing. The parser reads the page from top to bottom. A script inside <head> can run before the parser reaches <body>. At that moment, document.body is null, because the body doesn't exist yet.

Everything in the DOM tree is a node. An element is one kind of node. It comes from a tag, such as <p>, <button>, or <br>.

Some nodes are not elements. These are nodes too:

• the text between tags,
• comments, such as <!-- note -->,
• the doctype, <!DOCTYPE html>,
• document itself.

The next examples use a small list. When you run them here, the page holds a <ul> with two <li> items, Home and Docs, and a comment after them. Each item has a data-kind attribute.

const list = document.querySelector("ul");
const firstItem = list.firstElementChild;
console.log(firstItem.nodeType);
console.log(firstItem.nodeName);
console.log(firstItem.localName);
console.log(firstItem.hasAttribute("data-kind"));

1. Line 1 finds the list. document.querySelector("ul") returns the first <ul> on the page.
2. Line 2 gets the list's first element child, the first <li>.
3. Line 3 prints 1. nodeType is a number that says what kind of node this is, and 1 means "element".
4. Line 4 prints LI. In an HTML page, nodeName gives an element's tag name in capital letters.
5. Line 5 prints li. localName gives the same tag name in small letters.
6. Line 6 prints true. hasAttribute() checks whether the element has an attribute with that name. The attribute belongs to the element, but it is not a child node.

The table below lists the common kinds of node. Read one row at a time: the kind of node, the nodeType number it has, the nodeName it has, and an example.

The last row needs a few words. A document fragment is a node that JavaScript makes, not the parser. You can build several new elements inside it, then add them all to the page in one step. When you do that, the elements move into the page and the fragment itself stays out. So you won't find a fragment when you look at a page's tree.

Now count the children of the same list. The list in the HTML has spaces and line breaks between its tags, and a comment at the end.

const list = document.querySelector("ul");
console.log(list.childNodes.length);
console.log(list.children.length);
console.log(list.childNodes[0].nodeName);

1. Line 1 finds the list again.
2. Line 2 counts every child node with childNodes. It prints 7.
3. Line 3 counts only the element children with children. It prints 2.
4. Line 4 asks for the name of the very first child node. It prints #text: the line break and spaces before the first <li>.

Now sort the cards. Be careful with class="x". It is an attribute. You can read it through element.attributes, but it is not a child node in the tree.

The words inside an element are not stored on the element itself. They are a separate node, a text node, and that node is a child of the element.

Spaces and line breaks between tags are called whitespace. Whitespace between tags usually becomes text nodes too. That is why childNodes often holds more items than you expect.

DevTools is the set of tools built into the browser for looking inside a page. Its Elements panel usually hides text nodes that hold only whitespace, so the tree is easier to read. JavaScript still sees them.

The table compares the two lists of children. Read each row as a question, then the answer for childNodes and for children.

The step-through below uses a plain object with two arrays. The arrays copy the two lists from a real parent: one text node, a P element, a comment, and a BR element.

1const box = {Run2  childNodes: ["#text", "P", "#comment", "BR"],3  children: ["P", "BR"],4};5console.log(box.childNodes.length);6console.log(box.children.length);

Now look at what the parser really builds. The viewer below takes the HTML you type and parses it in your browser with new DOMParser().parseFromString(html, "text/html"). DOMParser is a built-in tool that turns a string of HTML into a separate DOM tree.

The viewer is safe to play with:

• DOMParser does not run any scripts in your HTML.
• The viewer turns each node into a plain row of text and shows only those rows.
• Your HTML is never put into this lesson page.

Read a tree from the root down. The step-through below puts the first three rows of a small page's tree in a plain array, then prints them in order. It replays recorded example code; it is not the browser's own debugger.

1const labels = ["Document", "<!DOCTYPE html>", "<html>"];Run2console.log(labels[0]);3console.log(labels[1]);4console.log(labels[2]);

1const parsed = new DOMParser().parseFromString(html, "text/html");2const plainTree = convertDomNode(parsed);3renderRows(treeToRows(plainTree, { hideWhitespace }));

The HTML parser never stops with an error. When your HTML has a mistake, the parser fixes it and builds a tree anyway. Here are some fixes it makes:

• If <html>, <head>, or <body> is missing, the parser adds it.
• If table rows sit right inside <table>, the parser wraps them in a <tbody> element. <tbody> means "table body".
• If a <div> appears inside an open paragraph, the parser closes the paragraph before the <div>.
• If formatting tags such as <b> and <i> are closed in the wrong order, the parser rebuilds them into a correct tree. The rules for this have a nickname: the adoption agency algorithm.

A table is the easiest fix to check. The code parses a table with one row and one cell, then asks what is inside.

const parsed = new DOMParser().parseFromString(
  "<table><tr><td>Total</td></tr></table>",
  "text/html",
);
console.log(parsed.querySelector("table").firstElementChild.nodeName);
console.log(parsed.querySelector("tbody").firstElementChild.nodeName);

1. Lines 1 to 4 parse the HTML string into a new DOM tree called parsed.
2. Line 5 finds the table and prints the name of its first element child. It prints TBODY, not TR. The parser put a <tbody> between the table and the row.
3. Line 6 finds that <tbody> and prints the name of its first element child. It prints TR: the row now sits inside the <tbody>.

1const parsed = new DOMParser().parseFromString(snippet, "text/html");2const tree = convertDomNode(parsed);3const html = parsed.documentElement.outerHTML;

<table><tr><td>A</td></tr></table>

The best way to learn the DOM is to look at a real page. Most browsers have two DevTools panels for this:

• the Elements panel (called Inspector in Firefox), which shows the DOM tree,
• the Console, where you can type JavaScript and see the result.

1. Open DevTools, then open the Elements or Inspector panel.
2. Choose Inspect, then click a heading, paragraph, or button on this page. When you move the mouse over a node in the panel, the browser shades that part of the page.
3. Open the Console. In most browsers, $0 means "the node selected in the Elements panel right now". Try $0.nodeName and $0.localName.
4. Compare $0.childNodes with $0.children. Click each result to open it.
5. Right-click a node or a logged value and look for "Store as global variable". Most browsers then give it a short name, such as temp1, that you can use in the Console.
6. Change some HTML in the Elements panel. You are changing the DOM tree in this tab. The file on the server stays the same.

Where you will use this

You need the DOM tree whenever your code has to:

• find an element near another element,
• remove a message, or add a new card,
• read the text on the page,
• work out why a search for an element found the wrong one.

Tools such as React often change the DOM for you. But in the end, the browser still gets a tree of nodes, and you still debug that tree.

const list = document.querySelector("ul");
const names = [...list.children].map((item) => item.textContent.trim());
console.log(names.join(", "));

1. Line 1 finds the list.
2. Line 2 makes an array from the list's element children with [...list.children]. Then .map() turns each item into its text. textContent is the text inside an element, and .trim() removes spaces at the start and end.
3. Line 3 joins the names with a comma and prints them. For the small list in this lesson, it prints Home, Docs.

You can use the same steps to build a menu, a cart, or a to-do list from HTML that is already on the page.

Which list of children should you use?

• Use children when you only want elements. This is most of the time.
• Use childNodes when text nodes and comments matter too. A text editor or a tool like the viewer above needs this.

When you debug, keep two views apart:

• View Source shows the HTML text the server sent.
• The Elements panel and document show the tree after the parser fixed the HTML and after scripts changed it.

If a search for an element gives a strange result, compare these two views first.

Common misconceptions

• "The DOM is the same as my HTML file." The DOM is the tree the parser built. The parser may have fixed things, and scripts may have changed it since.
• "Every node is an element." Text, comments, the doctype, document fragments, and document are nodes too. They are not elements.
• "Spaces between tags disappear." They usually become text nodes. The parser drops whitespace only in a few places, such as before <head>.
• "Attributes are children." You can read them through attributes, but they are not child nodes.
• "DevTools shows every node JavaScript can see." The Elements panel may hide text nodes that hold only whitespace, so the tree is easier to read.
• "Broken HTML makes the parser throw an error." The HTML parser does not stop. It fixes many mistakes and still builds a tree.

Key takeaways

• The DOM is a live tree of nodes that the browser builds from your HTML.
• Elements are nodes. Text, comments, the doctype, document fragments, and document are nodes too.
• childNodes holds every child node. children holds only the child elements.
• The HTML parser fixes many mistakes, so the DOM can be different from the HTML you typed.
• In DevTools, $0 is the node you selected, so you can inspect it with JavaScript.

One-line definition: the DOM tree is the live tree of objects the browser builds from a page's HTML, after fixing its mistakes.

Up next: Walking & searching the DOM.