JavaScript Document createNodeIterator() Method

What You’ll Learn

document.createNodeIterator() is an instance method that returns a NodeIterator for walking a DOM subtree (see MDN Document: createNodeIterator()). Learn root, whatToShow, custom filters, nextNode() loops, how it compares to TreeWalker and querySelectorAll, and five try-it labs.

Introduction

Sometimes you need every matching node under a branch of the tree — including text nodes or comments that CSS selectors ignore. A NodeIterator walks that subtree in document order.

document.createNodeIterator(root, whatToShow, filter) builds the iterator. Then you call nextNode() until it returns null. MDN’s example collects every <p> under document.body that passes a filter.

For simple element lists, querySelectorAll is often enough. Use NodeIterator when you need node-type control or text/comment traversal.

Related tutorials: createExpression(), nodeType, createElement().

Understanding document.createNodeIterator()

An instance method on the page’s document object (MDN Document interface).

• root — node where traversal begins (MDN).
• whatToShow — optional bitmask of NodeFilter show constants; default SHOW_ALL (MDN).
• filter — optional callback or { acceptNode } object (MDN).
• Return value — a new NodeIterator (MDN).
• Walk — nextNode() / previousNode() move the cursor.
• Reject vs skip — for this API, FILTER_REJECT and FILTER_SKIP are equivalent (MDN).

📝 Syntax

General forms of Document.createNodeIterator (MDN):

createNodeIterator(root)
createNodeIterator(root, whatToShow)
createNodeIterator(root, whatToShow, filter)

Parameters

• root — the root node for the iterator’s traversal (MDN).
• whatToShow (optional) — unsigned long bitmask from NodeFilter constants. Defaults to 0xFFFFFFFF ((SHOW_ALL) (MDN).
• filter (optional) — a function, or an object with acceptNode(), returning FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP (MDN).

Return value

A new NodeIterator object (MDN).

MDN example (callback filter)

const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  (node) =>
    node.nodeName.toLowerCase() === "p"
      ? NodeFilter.FILTER_ACCEPT
      : NodeFilter.FILTER_REJECT,
);
const pars = [];
let currentNode;

while ((currentNode = nodeIterator.nextNode())) {
  pars.push(currentNode);
}

📋 Common whatToShow constants

Useful NodeFilter show flags from MDN (not an exhaustive list):

Combine flags with bitwise OR, for example NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT.

⚖️ createNodeIterator vs related APIs

Examples Gallery

Examples follow MDN Document: createNodeIterator() and everyday DOM traversal patterns.

const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  (node) =>
    node.nodeName.toLowerCase() === "p"
      ? NodeFilter.FILTER_ACCEPT
      : NodeFilter.FILTER_REJECT,
);

const pars = [];
let currentNode;
while ((currentNode = nodeIterator.nextNode())) {
  pars.push(currentNode);
}
console.log(pars.length);

2
(or however many <p> elements are under body)

const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return node.nodeName.toLowerCase() === "p"
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT;
    },
  },
);

const pars = [];
let currentNode;
while ((currentNode = nodeIterator.nextNode())) {
  pars.push(currentNode.textContent.trim());
}
console.log(pars);

["Hello", "World"]

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

const chunks = [];
let node;
while ((node = it.nextNode())) {
  const t = node.nodeValue.trim();
  if (t) chunks.push(t);
}
console.log(chunks);

["Alpha", "Beta"]

const root = document.getElementById("panel");
const mask = NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT;
const it = document.createNodeIterator(root, mask);

const kinds = [];
let node;
while ((node = it.nextNode())) {
  kinds.push(node.nodeType === Node.COMMENT_NODE ? "comment" : node.nodeName);
}
console.log(kinds);

["DIV", "comment", "SPAN"]
(exact order depends on markup)

const it = document.createNodeIterator(
  document.getElementById("list"),
  NodeFilter.SHOW_ELEMENT,
  (node) =>
    node.nodeName.toLowerCase() === "li"
      ? NodeFilter.FILTER_ACCEPT
      : NodeFilter.FILTER_REJECT,
);

const first = it.nextNode();
const second = it.nextNode();
const back = it.previousNode();

console.log(first.textContent, second.textContent, back.textContent);
// e.g. "One" "Two" "Two"

One Two Two

🚀 Common Use Cases

• Collect filtered elements — walk a branch and keep only certain tags (MDN p sample).
• Text extraction — iterate SHOW_TEXT under a container.
• Comment / PI scans — nodes CSS cannot select.
• Custom accept rules — class names, data attributes, or content checks in acceptNode.
• Not always needed — prefer querySelectorAll for simple element lists.
• Need tree moves? — consider createTreeWalker instead.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• For createNodeIterator, FILTER_REJECT and FILTER_SKIP are equivalent (MDN).
• SHOW_ATTRIBUTE is special — prefer Element.attributes for attributes (MDN).
• Some older show constants (SHOW_ENTITY, …) are legacy and no longer effective (MDN).
• Iterator position matters when mixing nextNode and previousNode.
• Related: createExpression(), nodeType, createDocumentFragment().

💡 Best Practices