JavaScript NodeIterator nextNode() Method

What You’ll Learn

The nextNode() method of a NodeIterator returns the next node in document order and advances the iterator. Learn the first-call behavior, null at the end, common while loops, and how it works with filter and whatToShow—with five examples and try-it labs.

Introduction

After you create a NodeIterator with document.createNodeIterator(root, whatToShow, filter), you walk the subtree by calling nextNode(). Each call moves one step forward in document order.

The first call to nextNode() returns the first node in the set. When there are no more nodes, it returns null—the usual signal to stop looping.

Understanding the nextNode() Method

An instance method on NodeIterator that returns the next node in the iterator’s set and advances the iterator position.

• Returns — a Node, or null when done.
• Parameters — none.
• First call — returns the first node in the set (MDN).
• Advances — updates referenceNode and pointerBeforeReferenceNode.
• Respects — whatToShow bitmask and filter.acceptNode().
• Baseline Widely available on MDN (since July 2015).

📝 Syntax

Call the method on a NodeIterator:

nodeIterator.nextNode()

Parameters

None.

Return value

A Node representing the next node in the set, or null if the current node is the last one.

Typical pattern (MDN idea)

const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return NodeFilter.FILTER_ACCEPT;
    },
  },
);

const currentNode = nodeIterator.nextNode(); // first node in the set

⚖️ nextNode() vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.nextNode. Labs walk real DOM subtrees with SHOW_ELEMENT and custom filters.

const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  { acceptNode: () => NodeFilter.FILTER_ACCEPT },
);

const currentNode = nodeIterator.nextNode();
console.log(currentNode.nodeName); // e.g. "HTML" or first element in set

HTML

const it = document.createNodeIterator(
  document.getElementById("box"),
  NodeFilter.SHOW_ELEMENT,
);

let count = 0;
let node;
while ((node = it.nextNode())) {
  count++;
}
console.log(count); // number of element nodes visited

3

const it = document.createNodeIterator(
  document.getElementById("box"),
  NodeFilter.SHOW_ELEMENT,
);

const tags = [];
let node;
while ((node = it.nextNode())) {
  tags.push(node.nodeName);
}
console.log(tags); // ["DIV", "SPAN", "SPAN"]

["DIV","SPAN","SPAN"]

const it = document.createNodeIterator(
  document.getElementById("box"),
  NodeFilter.SHOW_ELEMENT,
);

const first = it.nextNode();
console.log(it.referenceNode === first); // true

const second = it.nextNode();
console.log(it.referenceNode === second); // true

true
true

const it = document.createNodeIterator(
  document.getElementById("box"),
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return node.classList.contains("pick")
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT;
    },
  },
);

const picked = [];
let node;
while ((node = it.nextNode())) {
  picked.push(node.textContent.trim());
}
console.log(picked); // ["A", "B"]

["A","B"]

🚀 Common Use Cases

• Walk all elements in a subtree in document order.
• Collect nodes that pass a custom acceptNode filter.
• Process DOM nodes one at a time without building a full NodeList first.
• Traverse mixed content when paired with whatToShow flags.
• Debug iterator state via referenceNode after each step.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• First nextNode() returns the first node, not the second.
• null means the walk is finished—do not treat it as a valid node.
• Pair with whatToShow and filter for precise walks.
• Do not call deprecated detach() before walking.
• Related learning: referenceNode, root, childNodes.

💡 Best Practices