DOM API Essentials: Structure, Events, Observers, Cancellation

The DOM is one large API surface arranged around a small set of design choices: a layered interface hierarchy that separates universal element operations from markup-specific ones; two collection types whose liveness rules decide whether your iteration is correct; a quiet split of mutation methods between the ParentNode and ChildNode mixins; an event model whose three-phase dispatch and shadow-boundary retargeting are spec-defined, not implementation detail; observer APIs whose delivery timing is part of the spec; and an AbortSignal primitive that is now the standard way to cancel everything from a fetch to an addEventListener. This article is the mental model and reference for those layers, written for senior engineers who want to know why the surface looks the way it does, not just which method to call.

The normative source is the WHATWG DOM Living Standard, with HTML-element specifics in the WHATWG HTML Living Standard. Everything below traces back to those two specs unless noted.

Mental model in seven rules

• Element is the markup-neutral base. querySelector, getAttribute, and classList live on Element so they work for HTML, SVG, and MathML alike. Markup-specific behavior (text content semantics, editability, accessibility hooks) lives on HTMLElement.
• A small set of HTML-ish properties are shared with SVG. dataset, tabIndex, autofocus, nonce, focus(), and blur() come from the HTMLOrSVGElement interface mixin, not from HTMLElement — they are valid on both <div> and <svg>.¹
• Collections are live by default. The DOM Standard states that “a collection can be either live or static. Unless otherwise stated, a collection must be live.”² Only querySelectorAll (and StaticRange) opt out.
• Mutation methods come in two flavors. Old DOM-1 methods (appendChild, removeChild, insertBefore) operate from the parent’s perspective. Modern methods on the ParentNode and ChildNode mixins (append, prepend, replaceChildren, before, after, replaceWith, remove) accept variadic Node | string arguments and are how you should be writing new code.
• Every event has three phases — but the target sees both. Dispatch is a fixed sequence of capture (root → target), target, then bubble (target → root). The “capture” / “bubble” choice for a listener decides which traversal it sees; listeners on the actual target run regardless of that flag.³
• Observers do not run synchronously. MutationObserver is a microtask; ResizeObserver runs in a defined slot between layout and paint; IntersectionObserver and PerformanceObserver are driven by the rendering steps. Each timing slot has consequences for what you can safely do inside the callback.
• AbortSignal is the unified cancellation primitive. addEventListener, fetch, ReadableStream, setTimeout (where supported), WebSocketStream, and any well-designed async API now accept a signal. One controller.abort() tears down everything attached to that signal — and AbortSignal.any([…]) lets you compose them.⁴

The interface hierarchy

Each interface is a thin layer that adds capabilities to its ancestor. Cross-markup compatibility is the reason Element and HTMLElement exist as separate types: an SVG <circle> is a perfectly real Element but is not an HTMLElement.

What each layer adds

• EventTarget — addEventListener, removeEventListener, dispatchEvent. Anything that can receive events is one, including Window, XMLHttpRequest, AbortSignal, message ports, and offscreen workers — not just elements. The interface even has a public constructor (new EventTarget()), which makes it a useful building block for in-process pub/sub.
• Node — tree participation: parentNode, childNodes, firstChild, lastChild, appendChild, removeChild, insertBefore, nodeType, nodeName, cloneNode. Text nodes, comments, document fragments, and the document itself are all Nodes.
• Element — the cross-markup element surface: getAttribute/setAttribute, classList, id, tagName, namespace-aware variants (getAttributeNS), CSS selectors (querySelector, querySelectorAll, matches, closest), and box geometry (getBoundingClientRect, getClientRects, scroll APIs). All work on HTML, SVG, and MathML elements.
• HTMLElement — HTML-specific semantics: innerText, outerText, contentEditable, isContentEditable, accessKey, lang, dir, translate, hidden, inputMode, enterKeyHint, popover, the inline-style style setter, the click() activation behavior, and (on supporting browsers) editContext for custom editable surfaces.⁵
• SVGElement — SVG-specific surface: ownerSVGElement, viewportElement, and SVG-specific style and class plumbing.
• HTMLOrSVGElement — a Web IDL interface mixin (not a class) shared by HTMLElement and SVGElement. It contributes dataset, nonce, autofocus, tabIndex, focus(), and blur(). This is the reason you can write circle.dataset.userId on an SVG element.¹

Why the split matters in practice

Typing a utility as Element instead of HTMLElement is the difference between “works on icons too” and “throws on the SVG sprite”:

1function setActive(el: Element, active: boolean): void {2  el.classList.toggle("active", active)3  el.setAttribute("aria-selected", String(active))4}56function setLabel(el: HTMLElement, text: string): void {7  el.innerText = text8}910const tab: Element = document.querySelector('[role="tab"]')!11const icon: Element = document.querySelector("svg.icon")!1213setActive(tab, true)14setActive(icon, true)

innerText is HTML-only, so setLabel correctly demands HTMLElement. TypeScript’s lib types reflect the spec — and the instanceof check is also a real runtime narrowing, not just a typing trick.

Selection and collection liveness

Five DOM methods give you a collection. They differ along two axes — type (HTMLCollection vs NodeList) and liveness (live vs static) — and the combination decides what loop patterns are safe.

The matrix

querySelectorAll is the odd one out: the spec defines it as returning the static result of running scope-match against the selectors string, and that snapshot is captured once.⁶ Everything else either explicitly returns a live HTMLCollection or — in the cases of childNodes and the spec quirk that is getElementsByName — a live NodeList.⁷

The for-i mutation footgun

Live collections re-evaluate as the DOM mutates. A naive for (let i = 0; i < items.length; i++) that removes the matched class from each element will skip every other one because the collection shrinks under the iterator:

1const items = document.getElementsByClassName("item")23for (let i = 0; i < items.length; i++) {4  items[i].classList.remove("item")5}67for (const item of [...document.getElementsByClassName("item")]) {8  item.classList.remove("item")9}

The same trap appears with for...of on a live collection if the body adds or removes matching elements. The fix is to materialize a snapshot first — Array.from(...), the spread operator, or just call querySelectorAll instead.

NodeList versus HTMLCollection capabilities

• NodeList has a native forEach. HTMLCollection does not.
• HTMLCollection has namedItem(name), which returns the first element whose id or name matches. NodeList has only item(index) and indexed access.
• Both are iterable with for...of, both support indexed access, and neither is an Array — map, filter, reduce, and the rest live on Array.prototype. Spread or Array.from to use them.
• Never use for...in on either — you will enumerate length and item along with the indices.

getElementById vs querySelector('#id')

Both work; their cost models differ. Every Document maintains an internal map from id attribute values to elements, kept in sync as the tree mutates — getElementById is a hash lookup against that map and is the spec-defined fast path for “find the element with this id”.⁸ querySelector walks a parsed selector against the scope’s tree using the standard scope-match algorithm; in modern engines, simple #id selectors are pattern-matched into the same id-map lookup, but anything more complex ('#id .child', 'main #id') drops out of that fast path and traverses normally.⁹

Practically: prefer getElementById when you actually have an id and you want the cheapest possible lookup; reach for querySelector when the predicate is anything richer than “this exact id”. The difference is usually invisible at single-call scale but compounds inside hot loops or framework reconciliation paths that resolve thousands of nodes per render.

Traversal and structural mutation

The DOM gives you four traversal surfaces. They overlap in capability but differ in what they include and how programmable they are.

Sibling and parent navigation

Every Node exposes parentNode, firstChild, lastChild, previousSibling, and nextSibling. Every Node that participates as an element also exposes the element-only variants on the NonDocumentTypeChildNode mixin: previousElementSibling and nextElementSibling. The element variants skip text nodes and comments — you almost always want them when walking siblings.

parentNode returns a Node; parentElement returns an Element or null (the document itself has no parent element). closest(selectors) walks up the ancestor chain (including the starting element) and returns the first ancestor that matches a CSS selector — the right tool for “find the enclosing form” or “find the nearest section”.

ParentNode and ChildNode mixins

Two interface mixins define the modern manipulation surface:

• ParentNode is implemented by Document, DocumentFragment, and Element. It contributes children, firstElementChild, lastElementChild, childElementCount, querySelector, querySelectorAll, and the variadic mutation methods append(...nodes), prepend(...nodes), replaceChildren(...nodes), and (newer) moveBefore(node, child).
• ChildNode is implemented by Element, CharacterData (text/comment), and DocumentType. It contributes before(...nodes), after(...nodes), replaceWith(...nodes), and remove().

All variadic methods accept (Node | string).... Strings become Text nodes automatically, which removes a whole class of document.createTextNode boilerplate. They also accept zero arguments — replaceChildren() with no arguments empties the parent, and remove() is the modern replacement for parent.removeChild(child) from child’s perspective.

1list.append(item, " · ", footer)2list.replaceChildren()3list.replaceChildren(...newItems)45stale.remove()6stale.replaceWith(replacement)7target.before("Section: ", heading)

Compared to the DOM-1 methods these are not just shorter; they are also unambiguous. parent.appendChild(node) returns the appended node and throws if node is not a Node. parent.append(node, " ", other) returns undefined and accepts any number of nodes and strings. The asymmetric return type is one of the small reasons DOM-1 code reads strangely today.

Fragments, ranges, and selections

For larger structural moves and editor-style operations, four interfaces become relevant:

• DocumentFragment is a parent-less container. Append a fragment to a real parent and the spec moves the fragment’s children to the parent and empties the fragment in one tree-mutating step.¹⁰ That coalesces what would otherwise be N separate insertions into one mutation observation and one layout invalidation.
• Range is a live boundary pair (startContainer, startOffset) to (endContainer, endOffset). The spec calls these “live ranges” because tree mutations move the boundary points as the underlying content shifts. range.deleteContents(), range.extractContents() (returns a DocumentFragment), and range.insertNode(node) let you operate on arbitrary slices of a tree, including across element boundaries.
• StaticRange is the snapshot equivalent: cheaper because it does not maintain itself across mutations. Used by InputEvent.getTargetRanges() and similar APIs that just need to describe a region without owning it.
• Selection is the user-visible selection — the highlighted text in a document. It is a single live range per document (multi-range selections were spec’d but never implemented in WebKit/Blink). window.getSelection() returns it; selection.getRangeAt(0) lifts it into a Range you can manipulate.

CSS Custom Highlight API: ranges without DOM mutation

Until 2025 the only way to render a “highlight” in the document was either to wrap the highlighted text in a <span> (mutating the DOM, which can disturb live ranges, observers, and editor state) or to lean on the user-controlled Selection. The CSS Custom Highlight API is the third option: register Ranges in the document’s Highlight registry and style them via the ::highlight() pseudo-element, with no DOM mutation at all.¹¹

1function highlightMatches(article: HTMLElement, query: string) {2  CSS.highlights.delete("search-results")3  if (!query) return45  const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT)6  const ranges: Range[] = []7  for (let node = walker.nextNode(); node; node = walker.nextNode()) {8    const text = node.nodeValue ?? ""9    const lower = text.toLowerCase()10    let from = 011    for (let i; (i = lower.indexOf(query.toLowerCase(), from)) !== -1; ) {12      const r = new Range()13      r.setStart(node, i)14      r.setEnd(node, i + query.length)15      ranges.push(r)16      from = i + query.length17    }18  }19  CSS.highlights.set("search-results", new Highlight(...ranges))20}

1::highlight(search-results) { background: #ff0; color: #000; }

Compared to Selection, ::highlight() lets you maintain multiple independent highlight layers (search results, spelling errors, collaborator cursors), it does not steal user focus from the actual selection, and it leaves the DOM unchanged — which means MutationObserver, IntersectionObserver sentinels, and live Ranges outside the registry are not perturbed. Use the API when the highlight is decorative or informational; reach for Selection only when you are actually setting the user’s selection.

TreeWalker and NodeIterator

CSS selectors only see elements. When you need to visit text nodes, comments, processing instructions, or to express a programmatic filter that no selector can capture, the DOM gives you the traversal API:

1const walker = document.createTreeWalker(2  article,3  NodeFilter.SHOW_TEXT,4  {5    acceptNode(node) {6      return /\d{4}-\d{2}-\d{2}/.test(node.nodeValue ?? "")7        ? NodeFilter.FILTER_ACCEPT8        : NodeFilter.FILTER_REJECT9    },10  },11)1213for (let n = walker.nextNode(); n !== null; n = walker.nextNode()) {14  highlightDate(n)15}

Two callable types live here:

• NodeIterator is a flat, in-order cursor with nextNode() / previousNode().
• TreeWalker maintains a currentNode and exposes hierarchical navigation (parentNode, firstChild, nextSibling, …) so you can walk by structure instead of in linear order.

NodeFilter.SHOW_* is a bitmask (SHOW_ELEMENT, SHOW_TEXT, SHOW_COMMENT, SHOW_ALL, …) that pre-filters by node type before the acceptNode callback runs. acceptNode returns FILTER_ACCEPT, FILTER_SKIP (skip this node, descend into its children), or FILTER_REJECT (skip this node and its subtree). For NodeIterator, FILTER_REJECT is treated identically to FILTER_SKIP — there is no concept of “subtree” in a flat iterator.¹²

Events: dispatch, composition, cancellation

Every Event traverses the tree in three spec-defined phases and every addEventListener chooses which phase it sees. The dispatch algorithm in DOM §2.9 is what makes the model predictable across HTML, SVG, custom elements, and shadow DOM.³

Capture, target, bubble

event.eventPhase reports CAPTURING_PHASE, AT_TARGET, or BUBBLING_PHASE while a listener runs. The third argument to addEventListener chooses which traversal a listener participates in — true (or { capture: true }) for capture, default false for bubble. The target itself fires both kinds, in the order they were added.¹³ stopPropagation() halts the rest of the path; stopImmediatePropagation() also skips remaining listeners on the current target.

A handful of events are non-bubbling by default: focus, blur, mouseenter, mouseleave, loadstart, progress, scroll (on most elements), and the media-element events. Use the bubbling counterparts (focusin/focusout, mouseover/mouseout) or capture-phase listeners on an ancestor when you need delegation.

Listener options that change behavior

addEventListener(type, listener, options) takes an options dictionary that controls more than capture vs bubble:

Two of these are quietly load-bearing for performance and lifetime management:

• passive: true is the difference between butter-smooth and janky scrolling. Chromium and WebKit treat wheel, touchstart, and touchmove listeners on Window, Document, and <body> as passive by default — the spec calls these the passive default targets.¹⁴ If you genuinely need to call preventDefault() on these, set passive: false explicitly.
• signal is the modern way to clean up listeners. One controller can tear down dozens of subscriptions, including MutationObservers and fetches, with a single abort().

EventInit, CustomEvent, and EventTarget as a base class

Event is constructible: new Event(type, { bubbles, cancelable, composed }). The composed flag controls whether the event crosses shadow boundaries. For carrying a payload, use CustomEvent:

1class Cart extends EventTarget {2  add(item: Item) {3    this.#items.push(item)4    this.dispatchEvent(new CustomEvent<Item>("itemadded", {5      detail: item,6      bubbles: false,7    }))8  }9  #items: Item[] = []10}1112const cart = new Cart()13cart.addEventListener("itemadded", (e: CustomEventMap["itemadded"]) => {14  console.log(e.detail.sku)15})

EventTarget’s public constructor makes it the right base for any in-process pub/sub bus — you get capture/bubble (vacuously), once, signal, and the rest of the listener machinery without inventing your own. Don’t import an event-emitter library when the platform ships one.

Shadow DOM and event retargeting

When an event is dispatched inside an open shadow tree, the algorithm composes a path that crosses the boundary. As the event propagates outside the shadow root, event.target is retargeted to the shadow host so that consumers of the host element never see internal nodes they were not given access to. Inside the shadow tree, event.target still points at the real target. event.composedPath() returns the full crossing path only if the event’s composed flag is true (UI events like click, keydown, input are composed; many synthetic events default to composed: false).¹⁵

1host.addEventListener("click", (e) => {2  console.log(e.target)         // the host (retargeted)3  console.log(e.composedPath()) // [button, …shadowRoot, host, body, html, document, window]4})

{ mode: "closed" } shadow roots elide their internals from composedPath() entirely — the path stops at the host. This is a privacy boundary, not a security boundary; treat it accordingly.

Cancellation as a first-class primitive

AbortController and AbortSignal (DOM §3) are the unified cancellation primitive across the web platform.¹⁶ Beyond fetch, every modern API that takes time accepts a signal — addEventListener, EventSource, ReadableStream.pipeTo, WritableStream.close, WebSocketStream, the streams cancel() family, and many newer APIs (scheduler.postTask, Web Locks, the View Transitions API). Two static helpers make composition cheap:

• AbortSignal.timeout(ms) returns a signal that aborts with a TimeoutError DOMException after ms milliseconds.
• AbortSignal.any([sig1, sig2, …]) returns a signal that aborts when any input aborts; the resulting signal.reason is the first input’s reason.⁴

The pattern that replaces nearly every “manual cleanup” idiom you used to write:

1function mount(host: HTMLElement) {2  const controller = new AbortController()3  const { signal } = controller45  host.addEventListener("click", onClick, { signal })6  window.addEventListener("resize", onResize, { signal, passive: true })78  const observer = new MutationObserver(onMutate)9  observer.observe(host, { childList: true, subtree: true })10  signal.addEventListener("abort", () => observer.disconnect(), { once: true })1112  fetch("/state", { signal }).then(applyState).catch(reportIfNotAbort)1314  return () => controller.abort()15}

One controller.abort() removes both listeners, disconnects the MutationObserver, and cancels the in-flight fetch. This is now the canonical lifecycle pattern — for components, for routes, for anything with a teardown.

Observer APIs

Four observers cover most of the DOM change surface: MutationObserver for tree changes, ResizeObserver for box-size changes, IntersectionObserver for visibility against a root rectangle, and PerformanceObserver for entries on the performance timeline. They share a tiny shape — new Observer(callback); observer.observe(target, options); observer.unobserve(target); observer.disconnect() — but each is timed differently, and the timing is the part of the spec you have to internalize.

Cleanup is your responsibility

None of the observer constructors take a signal directly. Wire them into the AbortSignal lifecycle by attaching a one-shot listener:

1function watch(host: Element, signal: AbortSignal) {2  const mo = new MutationObserver(handle)3  const ro = new ResizeObserver(handle)4  const io = new IntersectionObserver(handle, { threshold: [0, 1] })56  mo.observe(host, { childList: true, subtree: true })7  ro.observe(host)8  io.observe(host)910  signal.addEventListener("abort", () => {11    mo.disconnect()12    ro.disconnect()13    io.disconnect()14  }, { once: true })15}

Forgetting disconnect() is one of the most common leaks in long-lived SPAs: each observer keeps strong references to its targets and to the closure of its callback.

MutationObserver — microtask-timed

The DOM Standard schedules MutationObserver delivery via “queue a mutation observer microtask”, which sets a per-agent flag, queues a microtask to “notify mutation observers”, and clears the flag when the microtask runs.¹⁷ All mutations from a synchronous task therefore arrive in one callback invocation, scheduled on the microtask queue alongside resolved promises.

Practical consequences:

• Batching is automatic and inescapable. You cannot get a synchronous notification per mutation. If you need the synchronous behavior of the deprecated MutationEvent API, the answer is “you do not”.¹⁸
• Microtask, not task. Because delivery happens in the microtask checkpoint at the end of the current synchronous task, your callback runs before any subsequent rendering and before the next event loop task. Heavy work in the callback delays paint just like heavy work in a Promise.then.
• Records survive disconnection. observer.takeRecords() drains anything still queued when you disconnect(), useful when you want to flush before tearing down.

The options object must specify at least one of childList, attributes, characterData. Add subtree: true to watch the entire descendant tree, attributeFilter: ["class", "data-state"] to limit attribute watching, and attributeOldValue / characterDataOldValue to capture the prior value:

1function watchInvalid(form: HTMLFormElement, signal: AbortSignal) {2  const observer = new MutationObserver((records) => {3    for (const r of records) {4      if (r.type !== "attributes") continue5      const field = r.target as HTMLElement6      const errorId = field.getAttribute("aria-describedby")7      const errorEl = errorId ? document.getElementById(errorId) : null8      if (errorEl) {9        errorEl.hidden = field.getAttribute("aria-invalid") !== "true"10      }11    }12  })1314  for (const field of form.querySelectorAll("input, textarea, select")) {15    observer.observe(field, {16      attributes: true,17      attributeFilter: ["aria-invalid"],18      attributeOldValue: true,19    })20  }2122  signal.addEventListener("abort", () => observer.disconnect(), { once: true })23}

ResizeObserver — between layout and paint

The Resize Observer specification defines a deterministic slot in the rendering steps: after layout is up to date, the user agent gathers active observations, broadcasts them to your callback, and only then proceeds to paint.¹⁹ If your callback dirties layout for an element deeper in the tree than the deepest one whose observation it just delivered, the loop runs again at the new depth. If something stays dirty after the loop terminates, the user agent fires an ErrorEvent on Window with the message “ResizeObserver loop completed with undelivered notifications” and defers the leftovers to the next opportunity.²⁰

This timing is what makes ResizeObserver safe for layout-modifying callbacks: the changes you make invalidate layout but the user agent has not yet painted, so they coalesce into the same paint instead of triggering an extra one. It also explains the cardinal rule:

Other edge cases worth knowing:

• Three box options. box: "content-box" (the default), "border-box", or "device-pixel-content-box". Read the corresponding entry array — entry.contentBoxSize, entry.borderBoxSize, or entry.devicePixelContentBoxSize — instead of the legacy entry.contentRect, which only describes content-box CSS pixels.
• inlineSize and blockSize. The size entries are writing-mode aware; inlineSize is width in horizontal writing modes and height in vertical ones.
• CSS transforms do not fire. Transforms move pixels, not boxes — the spec explicitly excludes them.²¹
• Non-replaced inline elements report zero. They have no box of their own; observe a containing block-level element instead.
• Insertion and removal fire. A first observation arrives once after observe() if the element has any box; setting display: none reports zero dimensions in a fresh entry.

IntersectionObserver — driven by the rendering steps

IntersectionObserver watches whether a target is visible against a root (the viewport by default) inflated or shrunk by rootMargin, and fires when the visible ratio crosses any of the configured threshold values. The detailed mechanics (root, rootMargin, threshold semantics, sentinel patterns, batching, and when to prefer scroll listeners) are covered in the dedicated Intersection Observer API article. The two cross-cutting facts worth keeping in this article:

• Cross-origin privacy. When the target is in a cross-origin-domain document, entry.rootBounds is null and any rootMargin or scrollMargin offsets are ignored. The W3C spec says this prevents a cross-origin frame from “probing for global viewport geometry information that could deduce user hardware configuration”.²²
• Asynchronous batched delivery. Like the other observers, IntersectionObserver callbacks are batched and delivered as part of the rendering steps, so a single callback can carry intersection changes for many targets.

PerformanceObserver — the timeline subscription

PerformanceObserver subscribes to the Performance Timeline and is how you observe Core Web Vitals (largest-contentful-paint, layout-shift, event and first-input for INP), long animation frames (long-animation-frame), navigation, resource, and paint entries.²³ Two patterns dominate:

1new PerformanceObserver((list) => {2  for (const entry of list.getEntries()) {3    sendBeacon("lcp", entry.startTime, entry as PerformanceEntry)4  }5}).observe({ type: "largest-contentful-paint", buffered: true })67new PerformanceObserver((list) => {8  for (const e of list.getEntries() as PerformanceEventTiming[]) {9    if (e.duration > 40) reportSlowInteraction(e)10  }11}).observe({ type: "event", durationThreshold: 40, buffered: true })

buffered: true replays entries that arrived before the observer was constructed — essential for early-page metrics like LCP. Use the type/buffered form (not the older entryTypes array) when you need that replay or durationThreshold.

Custom editable surfaces: EditContext

The newest piece of the editor stack is the EditContext API (Chromium 121+, behind a flag in WebKit, Firefox not yet shipping). element.editContext = new EditContext() makes any element — including a <canvas> — focusable and connected to the OS text input service, with IME composition, dead keys, and language switching delegated to the platform. Combined with Selection, Range, and the CSS Custom Highlight API, this is the modern foundation for building a real editor in the browser without the contenteditable-and-pray approach that has failed every previous generation of editors.⁵

Compared to scroll/resize event listeners

The takeaway is not “always use observers” — pointermove and keydown will never be observers — but rather: any time you find yourself reaching for scroll/resize to derive geometry or structure, the observer API is the version that the platform optimized for that job.

Decision matrix: which API for which problem

Performance pitfalls

A short list of the patterns that consistently show up in profiles:

• Reading layout inside a write loop triggers forced synchronous layout. getBoundingClientRect, offsetTop, clientWidth, getComputedStyle all read live geometry. Either batch all reads before all writes, or do the geometric work inside a ResizeObserver/IntersectionObserver callback that runs after layout.
• Holding live collections across mutations keeps the document’s name/class indices warm. Convert to a snapshot ([...coll]) when you only need it once.
• Heavy MutationObserver callbacks delay paint because they run in the microtask checkpoint. Move expensive work to requestIdleCallback or scheduler.postTask({ priority: 'background' }).
• Non-passive wheel/touchmove listeners force scrolling onto the main thread. Always set passive: true unless you actually call preventDefault().
• One listener per child element for delegated events. Use a single capture-phase listener on the container and dispatch by event.target.closest(...).
• Unbounded ResizeObserver loops that mutate the observed element’s own box will eventually fire the loop error and skip a frame. Mutate a deeper element or defer to requestAnimationFrame.
• Forgotten observers and listeners in long-lived SPAs leak both DOM nodes and the closures their callbacks capture. Wire every subscription to an AbortSignal.

Practical defaults

• Type cross-markup utilities as Element. Reach for HTMLElement only when you actually need an HTML-only member.
• Default to querySelectorAll plus for...of. Keep live collections for the cases where you genuinely want auto-updating views.
• Prefer append/prepend/replaceChildren/before/after/replaceWith/remove over the DOM-1 methods. Use replaceChildren(...batch) to swap a subtree atomically; reach for DocumentFragment when you need to build the batch off-tree first.
• Use closest(selector) instead of hand-rolled parentNode walks, and previousElementSibling/nextElementSibling instead of the all-node sibling pointers.
• Default to MutationObserver over polling and over the deprecated MutationEvent API. Trust the microtask delivery; don’t wrap callbacks in setTimeout(..., 0) chasing some “more synchronous” behavior.
• Inside a ResizeObserver callback, avoid mutating the observed element’s own box. Modify a deeper element or defer to requestAnimationFrame.
• For visibility, reach for IntersectionObserver. For geometry-derived behavior on scroll, ask whether an observer can do it before reaching for a scroll handler.
• Pass { passive: true, signal } to every addEventListener you don’t need to preventDefault on. One AbortController per component teardown.
• For decorative or informational text highlights, reach for the CSS Custom Highlight API. Reserve Selection for actually setting the user’s selection.

Appendix

Prerequisites

• JavaScript fundamentals (classes and prototypal inheritance, microtasks, promises).
• Basic HTML/CSS.
• DevTools “Elements” and “Performance” panel familiarity.

Summary

• Element is the cross-markup base. HTMLElement adds HTML-only semantics; HTMLOrSVGElement is the mixin that gives dataset, tabIndex, autofocus, nonce, focus(), and blur() to both HTML and SVG.
• Collections are live by default. querySelectorAll is the only spec-static collection method; getElementsByName is the spec-quirk live NodeList.
• The modern manipulation API is the variadic ParentNode/ChildNode mixin methods. DocumentFragment, Range, and the CSS Custom Highlight API cover the rest of the structural-edit surface.
• TreeWalker/NodeIterator exist for traversals selectors cannot express (text/comment nodes, programmatic filters, subtree pruning).
• Events propagate capture → target → bubble; the target sees both phases. passive matters for scroll performance; signal matters for cleanup. Shadow DOM retargets event.target outside the boundary; composedPath() reveals the full path only for composed events.
• Observers have spec-defined timing. MutationObserver is microtask-timed. ResizeObserver runs between layout and paint with a depth-monotone loop and a defined error path. IntersectionObserver is driven by the rendering steps and suppresses geometry across origin boundaries. PerformanceObserver is the subscription model for the performance timeline.
• AbortController / AbortSignal is the unified cancellation primitive. AbortSignal.any and AbortSignal.timeout compose. Use one signal per unit of work and attach it to every cancellable thing the unit owns.

References

Specifications

• DOM Standard — WHATWG Living Standard.
• HTML Standard — DOM section — HTMLElement, HTMLOrSVGElement mixin, getElementsByName.
• Resize Observer — W3C Working Draft.
• Intersection Observer — W3C Working Draft.
• Performance Timeline Level 2 — PerformanceObserver, buffered flag.
• CSS Custom Highlight API Module Level 1.
• Selection API — W3C.
• EditContext API — W3C.
• SVG 2 — Basic Data Types and Interfaces.

MDN reference

• Element, HTMLElement, SVGElement
• NodeList, HTMLCollection
• ParentNode, ChildNode
• TreeWalker, NodeIterator, NodeFilter
• DocumentFragment, Range, StaticRange, Selection
• EventTarget, addEventListener, Event.composedPath, CustomEvent
• AbortController, AbortSignal, AbortSignal.any, AbortSignal.timeout
• Using shadow DOM
• MutationObserver, ResizeObserver, IntersectionObserver, PerformanceObserver
• CSS Custom Highlight API, EditContext API