Class: NodeList


The HTML DOM NodeList interface. Represents a collection of DOM Nodes.

NodeLists have almost the exact same API as NodeCollection, so there are a few caveats to take note of:

1. Unlike NodeCollections, NodeLists are immutable and therefore do not have any of the following functions:

  • clear
  • pop
  • push
  • shift
  • splice
  • unshift

If you want to manipulate a NodeList using these functions, you must retrieve it as a NodeCollection by calling .toNC() on the NodeList.

2. The following functions return the NodeCollection equivalent of the NodeList instead of the NodeList itself:

  • afterPut
  • appendWith
  • appendTo
  • beforePut
  • copyWithin (ES6 browsers only)
  • each
  • fill (ES6 browsers only)
  • putAfter
  • putBefore
  • prependWith
  • prependTo
  • remove
  • removeClass
  • replaceAll
  • replaceWith
  • reverse
  • sort
  • toggleClass
  • unwrap
  • wrapWith
  • wrapInner

This is because these functions will or may alter live NodeLists, as seen in this example:

var blueThings = $CLS('blue');  // ($CLS is Firebolt's alias for document.getElementsByClassName)
console.log(blueThings.length); // -> 10 (for example)

var ncBlueThings = blueThings.removeClass('blue');
blueThings.length === 0;   // -> true (since now there are no elements with the 'blue' class)
ncBlueThing.length === 10; // -> true (since `removeClass` returned the NodeList as a NodeCollection)

Returning a NodeCollection allows for correct functionality when chaining calls originally made on a NodeList, but be aware that a live NodeList saved as a variable may be altered by these functions.

3. Since it is not possible to manually create a new NodeList in JavaScript (there are tricks but they are slow and not worth it), the following functions return a NodeCollection instead of a NodeList:

  • add
  • clean
  • clone
  • concat
  • filter
  • intersect
  • map
  • slice
  • union
  • unique
  • without

This, however, should not be worrisome since NodeCollections have all of the same functions as NodeLists with the added benefits of being mutable and static (not live).

4. Passing a NodeList (or HTMLCollection) as a parameter to the NodeCollection#concat() function will add the NodeList itself to the collection instead of merging in its elements. This is because NodeLists and HTMLCollections don't directly inherit from NodeCollection/Array (they are merely given some of their functions), so they are treated as objects instead of arrays. A simple way to fix this is to call .toNC() on the NodeList/HTMLCollection when passing it as a parameter to concat like so:

var nodes = $QSA('div.special'),
    moreNodes = $TAG('p'),
    concatenation = nodes.concat( moreNodes.toNC() );