A NodeList is not an HTMLCollection

A guide to managing the DOM without a library is a genuinely useful thing to have, and most of them tell you about half of what you need.

Take picking nodes which is the first page anyone reads. What tends to get left out is that every one of those calls lives on both a Document and an Element and the difference is the whole point. Calling getElementsByClassName on the document hands back everything in the page carrying that class, and calling it on an element hands back only its own descendants carrying it. If you’re wrangling a large page then one of those is dramatically better than the other, and chaining them is one of the more useful things you can do with the raw platform.

Then there’s the ID lookup which is described as fetching the one item with that ID. That’s right in the sense that you get one element back and wrong in that it implies only one could exist. Browsers don’t enforce ID uniqueness. You get the first match and the rest sit there in silence which is a gotcha that catches people new to this constantly. A framework would at least complain about a duplicate key. The platform will not say a word.

The one that costs people the most time is querySelectorAll which does not return a list of elements. It returns a NodeList and a NodeList is a different thing from the HTMLCollection that the older methods hand back. They print the same. Their behaviour diverges the moment you touch them. They behave differently the moment you try to do anything interesting. You can call forEach on a NodeList and you cannot call map, which throws people a curve ball at exactly the point they thought they understood the API.

And the guide manages not to mention querySelector at all, the call you actually want for a single node and the one most people should be reaching for first.

None of this is an argument for using a library instead. The plain API is fine and knowing it properly is worth more over a career than knowing any particular framework, which is the case the guide is making and it’s a good case. It’s that a walkthrough that lists method names without telling you how they differ from each other isn’t teaching the API. It’s teaching a list of names and the differences between them are precisely where you’ll lose an afternoon.

That’s the thing to watch for when you read this kind of material and a page that shows you what to type is easy to write and easy to check. A page that tells you what the platform will do when you’re not expecting it takes somebody who has been caught by it and that is the part worth paying for when you reach for prose instead of a reference.

If you’re writing this sort of guide, the return types are where the value is, and everything else is discoverable in ninety seconds with an editor open.

The deeper habit worth building is to check what came back rather than assume. Log the constructor rather than the contents, because two things that print identically in a console can behave completely differently the moment you try to iterate them and the platform has several pairs like this waiting for you.

It takes about four seconds and it will save you an afternoon roughly once a year for the rest of your career.