JavaScript NodeIterator root Property

What You’ll Learn

The root property of a NodeIterator returns the fixed root Node of the subtree being traversed. Learn how it matches the first argument to createNodeIterator, how it differs from referenceNode, and why it never changes during a walk—with five examples and try-it labs.

Introduction

When you call document.createNodeIterator(root, ...), you choose where the walk begins and ends. The iterator remembers that node on its read-only root property—the top of the subtree it is allowed to traverse.

MDN’s classic example: if you pass document.body, then nodeIterator.root is document.body. That value stays the same even after you call nextNode() many times.

Understanding the root Property

A read-only instance property on NodeIterator that returns the node passed as the first argument to createNodeIterator.

• Returns — a Node object.
• Read-only — never changes for this iterator.
• Scope — defines the subtree the iterator can traverse.
• Not the same as referenceNode, which moves during walks.
• Baseline Widely available on MDN (since July 2015).

📝 Syntax

Read the property on a NodeIterator:

nodeIterator.root

Return value

A Node—the root of the traversal subtree.

Typical pattern (MDN idea)

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

const root = nodeIterator.root;
console.log(root === document.body); // true

⚖️ root vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.root. Labs show that root stays fixed while you walk the tree.

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

console.log(nodeIterator.root === document.body); // true

true

const box = document.getElementById("box");
const it = document.createNodeIterator(
  box,
  NodeFilter.SHOW_ELEMENT,
  { acceptNode: () => NodeFilter.FILTER_ACCEPT },
);

console.log(it.root.id); // "box"

box

const box = document.getElementById("box");
const it = document.createNodeIterator(
  box,
  NodeFilter.SHOW_ELEMENT,
  { acceptNode: () => NodeFilter.FILTER_ACCEPT },
);

const rootBefore = it.root;
it.nextNode();
it.nextNode();
console.log(it.root === rootBefore); // true

true

const box = document.getElementById("box");
const list = document.getElementById("fruit");

const itBox = document.createNodeIterator(box, NodeFilter.SHOW_ELEMENT);
const itList = document.createNodeIterator(list, NodeFilter.SHOW_ELEMENT);

console.log(itBox.root.id);   // "box"
console.log(itList.root.id);  // "fruit"

box
fruit

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

console.log("start", it.root === it.referenceNode); // often true
it.nextNode();
console.log("after", it.root === it.referenceNode); // false

start true
after false

🚀 Common Use Cases

• Verify which subtree an iterator was created for.
• Scope walks to a section element instead of document.body.
• Compare iterators by reading each root.
• Debug walks by checking root vs referenceNode.
• Teach the difference between fixed boundaries and moving anchors.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• root is read-only and fixed for the iterator’s lifetime.
• Do not confuse with referenceNode, which moves during walks.
• On creation, root and referenceNode often start as the same node.
• Related learning: referenceNode, filter, childNodes.

💡 Best Practices