Definition and Usage

NodeList is a collection of nodes selected from a web page, arranged in the order they appear in the DOM.

This collection is frequently used when working with the DOM and is an iterable, array-like object that lets you treat various nodes, including elements, like array items.

Note:
There are two main DOM collections when working with the HTML DOM: HTMLCollection and NodeList.
HTMLCollection is a collection of elements only, whereas NodeList, depending on how it's created, can include various nodes, such as elements, text, and comments. For more details, see JavaScript HTMLCollection and NodeList Comparison.

Features

  • NodeList is an array-like object and an iterable, which means it can be traversed using the for...of loop.
  • The length property returns the number of elements in the NodeList, just like in an array-like object.
  • Despite being array-like, you can use the forEach() method, which is typically used in arrays.
  • Depending on how it's created, NodeList may reflect live changes to the DOM or remain static.

Methods and Properties That Return NodeList Objects

Features of Methods and Properties That Return NodeList Objects
Category Returned Object Included Items Live Reflection
querySelectorAll() NodeList Elements only Static
Node.childNodes NodeList All child nodes
(text, comments, elements, etc.)		 Live reflection

Basic Example

Let's explore how to use NodeList objects and understand their features through the methods querySelectorAll() and Node.childNodes, which return NodeList objects.

querySelectorAll()

The querySelectorAll() method returns a NodeList object containing all elements that match the specified CSS selector, either within the HTML document or a specific element.

Syntax
JavaScript 
querySelectorAll(selectors)
Example Usage
HTML 
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>NodeList</title>
    </head>
    <body>
        <ul>
            <li>Pizza</li>
            <li>Burger</li>
            <li>Pasta</li>
        </ul>
        <script src="queryselectorall.js"></script>
    </body>
</html>
queryselectorall.js 
const liElements = document.querySelectorAll("li"); // Select all <li> elements
console.log(liElements); // NodeList(3) [li, li, li]

/* Method 1 - Using for...of loop */
for (const liElement of liElements) {
    console.log(liElement.textContent);
}
// Output: "Pizza" "Burger" "Pasta"

/* Method 2 - Using for loop */
for (let i = 0; i < liElements.length; i++) {
    console.log(liElements[i].textContent);
}
// Output: "Pizza" "Burger" "Pasta"

/* Method 3 - Using forEach() method */
liElements.forEach(li => { // Although it is array-like, forEach() can be used
    console.log(li.textContent);
});
// Output: "Pizza" "Burger" "Pasta"

Code Explanation
The for...of loop iterates over iterable objects.
The NodeList returned by querySelectorAll() is both array-like and iterable.

Code Explanation
The traditional for loop accesses elements using numeric indexes and the length property, both available on the NodeList.

Node.childNodes

The Node.childNodes property returns a collection of a specific node's child nodes. This collection is returned as a NodeList object.

Example Usage
JavaScript 
// Select an HTML element
const myElement = document.getElementById("myElement");

// Get the list of child nodes of myElement
const childNodes = myElement.childNodes;

// Iterate through the child nodes and print them
for (var i = 0; i < childNodes.length; i++) {
    console.log(childNodes[i]);
}

Code Explanation
The getElementById() method returns the element with the specified id attribute in the document.

The usage of the Node.childNodes property is not directly related to the main topic of this article, so it will not be covered here.

Not Live (Real-Time) Reflection of DOM Changes in Certain Cases

The NodeList object returned by the querySelectorAll() method does not reflect DOM changes in real-time (or live). However, the NodeList object returned by the Node.childNodes property does reflect DOM changes in real-time.

Here's an example where, after clicking the 'Add New Menu' button, a new <li> element is dynamically added to a <ul> element, but the number of <li> elements returned by document.querySelectorAll("li") (i.e., the number of items in the NodeList object) does not reflect the change in real-time.

HTML 
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>NodeList</title>     
    </head>
    <body>
        <ul id="list">
            <li>Pizza</li>
            <li>Burger</li>
            <li>Pasta</li>
        </ul>
        <p><code><li></code> element count: <strong id="li-length-val">3</strong></p>
        <button type="button" id="addButton">Add New Menu</button>
        <script src="none-live.js"></script>
    </body>
</html>
JavaScript - none-live.js 
// Get the NodeList
const liElements = document.querySelectorAll("li");

// Add a new <li> element when the button is clicked
document.getElementById('addButton').addEventListener("click", () => {
    const newLi = document.createElement("li");
    newLi.textContent = "New Menu Item";

    // Add the new <li> element to the <ul>
    document.getElementById("list").appendChild(newLi);

    // Check the number of <li> elements in real-time
    const liElementsLength = liElements.length; // liElements length is not updated in real-time
    document.getElementById("li-length-val").textContent = liElementsLength;
});

Code Explanation
The createElement() method creates a new HTML element and returns it.

Code Explanation
The appendChild() method adds a node as the last child of a specified parent node.

Live Demo

When a new element is added, you will see that the NodeList object does not reflect the change in real-time, and the number of <li> elements remains unchanged. This is in contrast to the HTMLCollection object, which reflects DOM changes in real-time.

Specifications

Browser Compatibility for NodeList
Specification
NodeList DOM Standard
#interface-nodelist

Browser compatibility

Browser Compatibility for NodeList
Object & Property
Desktop Chrome
Chrome
DesktopDesktop Edge
Edge
Desktop Firefox
Firefox
Safari
Safari
NodeList 1 12 1 1
length 1 12 1 1

References

See also