JavaScript Document createNodeIterator() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word CREATENODEITERATOR

Definition

document.createNodeIterator(root, whatToShow, filter) returns a NodeIterator that walks the DOM subtree under root. Call nextNode() (and optionally previousNode()) until you get null.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.createNodeIterator. Start with this line.

JavaScript
document.createNodeIterator(root[, whatToShow[, filter]])
CallWhat it does
document.createNodeIterator(root[, whatToShow[, filter]])Primary signature.
document.createNodeIterator(...)Call with the arguments your case needs.

Built into the browser. Call createNodeIterator(...) on document — no import required.

Library declarations
JavaScript
document.createNodeIterator(root[, whatToShow[, filter]])

Parameters

ParameterDescription
rootRequired. Start of the traversal subtree
whatToShowOptional. NodeFilter bitmask (default SHOW_ALL)
filterOptional. Callback or { acceptNode } object

Return Value

Return ValueDescription
*NodeIterator

JavaScript Examples

Example 1 — Walk Element Nodes

Create an iterator over elements under a root and list their tags.

JavaScript
const root = document.createElement("div");
root.innerHTML = "<span>A</span><b>B</b>";

const it = document.createNodeIterator(root, NodeFilter.SHOW_ELEMENT);
const names = [];
let node;
while ((node = it.nextNode())) {
  names.push(node.nodeName.toLowerCase());
}

console.log(names); // ["div", "span", "b"]
Try It Yourself

How It Works

  1. Build a small tree. A root div with two children.
  2. Create the iterator. SHOW_ELEMENT skips text nodes.
  3. Loop nextNode. Each call advances to the next matching node.
  4. Stop on null. When the walk finishes, nextNode() returns null.

Example 2 — Filter Only <p> Elements

MDN-style filter: accept paragraphs, reject other elements.

JavaScript
const root = document.createElement("div");
root.innerHTML = "<p>One</p><span>X</span><p>Two</p>";

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

const pars = [];
let currentNode;
while ((currentNode = it.nextNode())) {
  pars.push(currentNode.textContent);
}

console.log(pars); // ["One", "Two"]
Try It Yourself

How It Works

  1. Limit to elements. SHOW_ELEMENT feeds only elements to the filter.
  2. Accept paragraphs. Return FILTER_ACCEPT for p.
  3. Reject others. For NodeIterator, reject/skip both omit the node but keep walking children.
  4. Collect matches. The loop only sees accepted <p> nodes.

Example 3 — Collect Text Nodes

Use SHOW_TEXT to walk text content under a root.

JavaScript
const root = document.createElement("div");
root.innerHTML = "<p>Hi</p><p>JS</p>";

const it = document.createNodeIterator(root, NodeFilter.SHOW_TEXT);
const texts = [];
let node;
while ((node = it.nextNode())) {
  const t = node.data.trim();
  if (t) texts.push(t);
}

console.log(texts); // ["Hi", "JS"]
Try It Yourself

How It Works

  1. Mask text only. SHOW_TEXT ignores element wrappers.
  2. Advance with nextNode. Each match is a Text node.
  3. Trim whitespace. Skip empty whitespace-only text nodes.
  4. Read data. Use node.data (or textContent) for the string.
Compatibility

Browser Support

Document.createNodeIterator() is a long-standing DOM traversal API. MDN lists it as Baseline Widely available (since July 2015).

✓ Baseline · DOM

Document.createNodeIterator()

Supported in Chrome, Firefox, Safari, Edge, and other evergreen browsers. Safe for NodeIterator-based subtree walks.

99% Universal API
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
createNodeIterator() Excellent

Bottom line: Safe everywhere for DOM iteration. Need parent/sibling moves? Use createTreeWalker. See the MDN createNodeIterator() reference.

Frequently Asked Questions

It returns a new NodeIterator for walking the DOM subtree starting at a root node. You usually call nextNode() in a loop until it returns null.
No. MDN marks Document.createNodeIterator() as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
A new NodeIterator object.
An optional bitmask from NodeFilter constants (for example NodeFilter.SHOW_ELEMENT or SHOW_TEXT). It defaults to SHOW_ALL (0xFFFFFFFF).
A callback or an object with acceptNode() that returns FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. For createNodeIterator, FILTER_REJECT and FILTER_SKIP are equivalent — the node is skipped, but children continue to be considered.
Use TreeWalker when you need richer navigation (parentNode, firstChild, nextSibling, and so on). NodeIterator is a simpler forward/back iterator with nextNode() and previousNode().

Next: createNSResolver()

Learn document.createNSResolver() for XPath namespace resolvers (legacy helper).

createNSResolver() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document createExpression() Method JavaScript Document createNSResolver() Method