Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

What's the difference between a live HTMLCollection and a static NodeList?

Questions in this chapter (6)
  • Draft
  • medium
  • Askedvery often
  • Verified October 2026

Answer

The DOM Standard defines a collection as a list of nodes with a root and a filter, and says a collection is live unless stated otherwise. A live collection doesn't store its members: length and indexing answer from the tree as it is now. A static collection is a snapshot of the matches at creation time; later changes don't touch it.

Which one you get depends on the method, not the type:

Returns Type Live?
children, getElementsByTagName(), getElementsByClassName(), document.forms, table.rows HTMLCollection live
childNodes NodeList live
document.getElementsByName() NodeList live
querySelectorAll() NodeList static

The interfaces differ too. HTMLCollection holds only elements and adds namedItem() (lookup by id or name); the standard calls it "a historical artifact". NodeList can hold any node and has forEach(), keys(), values() and entries(). Both have length and indexing, and Web IDL gives every interface with an indexed getter a Symbol.iterator, so for…of, spread and Array.from() work on both; only NodeList has forEach().

Identity follows from liveness. children and childNodes return the same object every time; getElementsBy*() may return the same object for the same argument; querySelectorAll() always builds a new list.

Liveness bites when you change the tree while iterating it. Removing a class from each element of getElementsByClassName() in an index loop shifts the remaining items down and skips every other one. Inserting matching elements during for…of over a live collection can loop forever. Copy first ([...live]), use querySelectorAll(), or iterate backwards.

Example

// <ul id="list"><li class="todo">a</li><li class="todo">b</li><li class="todo">c</li></ul>
const list = document.getElementById('list');
const live = list.getElementsByClassName('todo'); // HTMLCollection, live
const snapshot = list.querySelectorAll('.todo');  // NodeList, static
const kids = list.childNodes;                     // NodeList, live

for (let i = 0; i < live.length; i++) live[i].classList.remove('todo');
console.log(live.length, live[0].textContent);
// → 1 b
console.log(snapshot.length);
// → 3

list.append(document.createElement('li'), 'text');
console.log(kids.length, list.children.length, snapshot.length);
// → 5 4 3

console.log(typeof live.forEach, typeof snapshot.forEach);
// → undefined function

Chrome 156 and Firefox 159 printed the same. b survives because removing a shifted it to index 0 after the loop had passed it.

Pitfalls

  • Assuming every NodeList is static. childNodes and getElementsByName() are live; only querySelectorAll() gives a snapshot.
  • Mutating a live collection's members in a forward loop. Matches drop out and indexes shift, so items get skipped.
  • Calling forEach() or map() on an HTMLCollection. It has neither; spread it or use Array.from().
  • Caching querySelectorAll() results and expecting new elements to appear. Query again, or keep a live collection when that's what you need.

Follow-ups

How do you get notified when a collection's contents change?
You don't: a live collection has no events. It only answers correctly when read. To react to tree changes, use a MutationObserver.
Why doesn't HTMLCollection get forEach()?
Its IDL has no iterable<> declaration, which is what generates forEach(). The standard discourages new APIs from returning HTMLCollection at all, recommending plain sequences (arrays) instead.

Exercises

How many times does this loop run?

// <p>1</p><p>2</p>
const ps = document.getElementsByTagName('p');
for (const p of ps) p.after(document.createElement('p'));

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.