Selection and Traversal APIs

## Two different kinds of lookup The DOM offers several ways to reach one element, and the two id-based routes work by different mechanisms. `document.getElementById(id)` is a *direct lookup*. The `id` argument is treated as a plain string, not as syntax. The document maintains an internal mapping from id values to elements, so the call is effectively a hash lookup, and it returns the matching `Element` or `null` when nothing matches. It never throws for a "weird" id, because there is nothing to parse. `document.querySelector(selectors)` is a *selector match*. The argument is a CSS selector list; the browser parses it, then finds the first element in tree order that matches, returning that `Element` or `null`. `#user-menu` is an id selector, which is only one of the things this method can express — `.card > a[href^="/docs"]` is equally valid. ```js document.getElementById('user-menu'); // Element | null document.querySelector('#user-menu'); // Element | null document.querySelector('nav a.active'); // any selector at all ``` ## Where each method lives `getElementById` is defined on `Document` and on `DocumentFragment` (which is why it also works on a shadow root). It is **not** on `Element`. There is no `container.getElementById('x')` — that call throws a `TypeError` because the method does not exist there. `querySelector` and `querySelectorAll` are defined on `Document`, `DocumentFragment`, **and** `Element`. Calling them on an element restricts the returned elements to that element's descendants, which is the usual way to scope a lookup inside a widget: ```js const panel = document.getElementById('settings'); const save = panel.querySelector('button[type="submit"]'); ``` ## The escaping trap HTML says an id must be at least one character long and must contain no ASCII whitespace. Everything else is legal: `3d-view`, `a.b`, `item:1`, `--x`. CSS is stricter. In a selector, an identifier may not start with a digit, and `.` and `:` are meaningful characters, so: ```js const el = document.createElement('div'); el.id = '3d-view'; document.body.append(el); document.getElementById('3d-view'); // the element document.querySelector('#3d-view'); // SyntaxError document.querySelector('#' + CSS.escape('3d-view')); // the element document.querySelector('[id="3d-view"]'); // the element ``` This matters most when the id comes from data — a database key, a slug, a generated value. The moment an id can start with a digit or contain punctuation, string-concatenating it into a selector is a bug waiting for the right record. `CSS.escape(value)` exists exactly for this and is the correct fix; the attribute selector `[id="..."]` is a readable alternative (its value is a quoted string, so only quotes and backslashes need escaping). Remember also that `querySelector` throws `SyntaxError` for *any* malformed selector, not just ids. If a selector is built from user or config input, that throw is part of your error surface. ## Duplicate and missing ids Ids are supposed to be unique in a document, but nothing enforces it at runtime. If two elements share an id, both routes return the **first one in tree order**, and the second is unreachable through either. `document.querySelectorAll('[id="dup"]')` is a quick way to find the duplicates when debugging. When nothing matches, both return `null` — not `undefined`, not an empty collection, and no exception. This is why `document.getElementById('nope').textContent` throws a `TypeError` about reading a property of `null`, one of the most common first-week errors in DOM code. Guard it, or use optional chaining when absence is genuinely acceptable. ## Which one should you use? For a known, hard-coded, well-formed id, both are fine and the choice is style. Modern engines special-case a lone id selector, so the performance argument that used to favour `getElementById` is not something you will measure in real code — pick on clarity, not on micro-benchmarks. Use `getElementById` when the id is a runtime value, because it sidesteps escaping entirely. Use `querySelector` when the lookup is naturally scoped to a subtree, when the condition is more than an id, or when you want one consistent selection API across your code. What you should not do is mix them up: passing a selector such as `'#user-menu'` to `getElementById` looks for an element whose id is literally `#user-menu`, and quietly returns `null`.