DOM

What it is

The DOM, short for Document Object Model, is the tree of objects a
browser builds from a page and keeps in memory for as long as the
page is open. The HTML parser reads the markup, and its output is a
document object: every element, every run of text and every comment
becomes a node, and each node knows its parent, its children and its
neighbours. Scripts read and change the page through that tree, and
what the browser draws is worked out from it.

The WHATWG maintains the model in the DOM Standard, whose own
summary names three things it covers without tying them to any one
platform: node trees, events, and the aborting of activities in
progress. The name is older than the standard. In its original sense
it meant an interface for reaching into a document and changing it;
today most people also say “the DOM” for the tree itself, and both
meanings are in daily use. The HTML Standard builds on top of it:
HTML defines the elements and what they do, the DOM Standard defines
what a node, an element, an attribute and an event are.

The tree is not the source file. A page's HTML is text that arrived
over the network. The DOM is what the parser made of that text, with
every parse error handled by rules the HTML Standard spells out, and
then changed by every script that has run since. The parser keeps
details that are easy to forget. The whitespace between two tags can
become a text node of its own, so the first child of an element is
not always the first element inside it, although the standard's own
example notes that not every stretch of whitespace turns into a text
node.

Nodes come in a handful of kinds. The document sits at the root,
with a doctype, elements, text nodes and comments beneath it. A
document fragment is a light container that sits outside the page's
tree, which makes it a handy place to assemble a block before
inserting it in one move. An element can also host a shadow tree, a
separate tree of its own that the document's ordinary queries do not
reach into.

Lists of nodes come in two kinds, and the difference matters. The
standard's rule is that a collection is live unless stated
otherwise: `childNodes` and the HTMLCollection from
`getElementsByClassName()` change as the tree changes.
`querySelectorAll()` is the stated exception and returns a static
list, a snapshot taken at the moment of the call.

The same standard defines how events travel. An event is dispatched
at a target node and passes through three phases: capturing, on the
way down from the top of the tree through the target's ancestors; at
the target itself; and bubbling, back up through the ancestors. The
`eventPhase` property reports where it is, as 1, 2 or 3, and 0 when
the event is not being dispatched. A listener added with
`addEventListener()` takes options: `once` removes it after its
first call, `passive` promises that it will not call
`preventDefault()`, and `signal` ties it to an `AbortController`, so
that aborting the controller removes the listener.

Why it matters

Every script that changes a page works through the DOM, whatever
language or framework it was written in. A framework adds a layer of
its own on top, but what the reader finally sees is nodes in this
tree. Next.js describes hydration as React attaching event handlers
to the DOM, which is how HTML sent from the server becomes a page
that responds to clicks. A team that knows the tree underneath can
debug what the framework actually did, rather than what it was asked
to do.

The tree is also where text and markup part ways. A string assigned
to `textContent` replaces an element's children with a single text
node and is never read as markup. The same string assigned to
`innerHTML` is handed to the HTML parser, and the HTML Standard
notes that those setters remove nothing dangerous by default. Which
of the two a page uses decides whether a visitor's display name is
shown as text or run as code.

What a reader experiences depends on more than the tree. Styles
decide whether a node is visible, where it sits and whether a
pointer can reach it, and none of that is visible to a tool that
only walks the nodes. That gap is where automated checks are most
often wrong, and it is the reason to test a page as rendered as well
as the document behind it.

Finally, the DOM is the contract between a page and everything that
reads it after the server has finished. Tests that click through a
page, browser extensions and assistive software all start from the
live tree. The other side of that contract is easy to miss: a
crawler that does not run JavaScript sees only the HTML that was
sent, and none of the nodes that scripts add later.

What it looks like in practice

The script below, written for this article, fills a list of orders
from data, keeps a single click listener on the list rather than one
per item, and can remove that listener later with one call.
`openOrder` stands for whatever the page does when an order is
chosen.

```js
const list = document.querySelector("#orders");
const controller = new AbortController();

function render(orders) {
  const items = orders.map((order) => {
    const li = document.createElement("li");
    li.dataset.id = order.id;
    li.textContent = `${order.number}: ${order.status}`;
    return li;
  });
  list.replaceChildren(...items);
}

list.addEventListener(
  "click",
  (event) => {
    const li = event.target.closest("li");
    if (li) openOrder(li.dataset.id);
  },
  { signal: controller.signal },
);

// When the view goes away:
controller.abort();
```

Each part maps onto the standard. `createElement()` makes an element
that belongs to no parent until it is inserted. `textContent` puts
the order number in as text, so a status that happens to contain
angle brackets stays a status. `replaceChildren()` removes the old
items and inserts the new ones in a single operation. The one
listener on the list serves every item because a click on an item
bubbles up to the list, and `closest()` walks from whatever was
clicked to the nearest `li`. Aborting the controller removes the
listener without the page having to keep a reference to the
function.

The tree also explains a class of defects that this site's own
review turned up. In an accessibility review carried out in August
2026, the site passed its automated rules and still had eleven
defects, every one of them down to how the page rendered rather than
to what its markup said. Eight footer links stayed in the tab order
behind `pointer-events`, a property that removes pointer interaction
and nothing else. To anything reading the document they were
ordinary links; a pointer never reached them, and the keyboard still
stopped on every one. A scroll-driven animation clipped the footer
off three pages. Of the four rules the review left behind, one reads
as a warning against trusting the tree alone: visibility has to be
established from the rendered pixels, not merely from the document
tree.

Where it goes wrong

A loop over a live collection skips every other item. The
HTMLCollection from `getElementsByClassName()` is live, so a loop
that removes the class from each element by index shrinks the
collection under itself and steps over every second element. Iterate
a static list instead: `querySelectorAll()` returns one, and
`Array.from()` turns a live collection into a plain array first.

```js
const pending = document.getElementsByClassName("pending");
for (let i = 0; i < pending.length; i++) {
  pending[i].classList.remove("pending"); // skips every other one
}

for (const el of document.querySelectorAll(".pending")) {
  el.classList.remove("pending"); // static list: all of them
}
```

Listeners pile up. A view that adds its listeners every time it
renders, and never removes them, runs each handler once per render:
after three visits, one click sends three requests. Removing a
listener by hand takes the very same function object that was added,
and an arrow function written inline at the call leaves nothing to
pass back. Pass a `signal` from one `AbortController` per view, as
in the example above, and a single `abort()` removes every listener
the view added; use `once: true` for a listener that should fire
only one time.

Text goes in as markup. Building a string of HTML from data and
assigning it to `innerHTML` gives the data to the parser, with no
sanitizing by default. A display name that carries markup, an image
tag with an error handler for instance, arrives on the page as a
real element with its handler attached. Text belongs in
`textContent` or in a text node made with `createTextNode()`. Where
markup really must come from a string, the HTML Standard defines
`setHTML()`, which sanitizes as it parses and removes unsafe
content.

An observer feeds itself. A `MutationObserver` reports changes to
the nodes it watches, and its callback runs after each batch of
changes. A callback that writes to the subtree it observes, to add a
counter or correct a class, creates new records and is called again,
and the page can lock up in a loop of its own making. Watch only
what has to be watched, with `attributeFilter` and without `subtree`
where possible, have the callback check whether its change is
already in place before writing, or call `disconnect()` before the
write and `observe()` again after it.

Further reading

  * DOM Standard — the WHATWG's definition of nodes, trees, live and
static collections, events, `AbortController` and
`MutationObserver`.

  * Parsing HTML documents — how the HTML parser turns a stream of
characters into a document object, parse errors included.

  * Dynamic markup insertion — `innerHTML`, `setHTML()` and
`setHTMLUnsafe()`, and which of them sanitize.

  * Server and Client Components — the Next.js account of hydration:
HTML from the server, then event handlers attached to the DOM.

hThis page on the web	URL:https://engineer.company/glossary/dom/	engineer.company	70
