JavaScript NodeIterator referenceNode Property

What You’ll Learn

The referenceNode property of a NodeIterator returns the anchor Node the iterator is tied to. Learn how it starts at the walk root, updates with nextNode(), pairs with pointerBeforeReferenceNode, and stays meaningful when the DOM changes—with five examples and try-it labs.

Introduction

A NodeIterator walks a DOM subtree, but it always has an anchor: the node stored in referenceNode. That is the node the iterator position is defined relative to.

MDN’s idea: after document.createNodeIterator(...), read nodeIterator.referenceNode to see the anchor. As you call nextNode() or previousNode(), this property updates to reflect the new anchor.

Understanding the referenceNode Property

A read-only instance property on NodeIterator that returns the current anchor Node.

• Returns — a Node object.
• Read-only — updated by iterator movement, not by assignment.
• Initial value — typically the root passed to createNodeIterator.
• DOM changes — MDN: iterator stays anchored to this node as nodes are inserted.
• Baseline Widely available on MDN (since April 2018).

📝 Syntax

Read the property on a NodeIterator:

nodeIterator.referenceNode

Return value

A Node—the iterator’s anchor.

Typical pattern (MDN idea)

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

const node = nodeIterator.referenceNode;
console.log(node.nodeName); // often "BODY"

⚖️ referenceNode vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.referenceNode. Labs show how the anchor changes as you walk the tree.

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

console.log(it.referenceNode === root); // true

true

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

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

true

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

console.log(it.referenceNode.nodeName); // "DIV"
it.nextNode();
console.log(it.referenceNode.nodeName); // "SPAN" (first child element)

DIV
SPAN

const it = document.createNodeIterator(
  document.getElementById("fruit"),
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return node.nodeName === "LI"
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT;
    },
  },
);

const log = [];
let node;
while ((node = it.nextNode())) {
  log.push(it.referenceNode.textContent);
}

Apple
Banana
Cherry

function logAnchor(it) {
  return it.referenceNode.nodeName + " before=" + it.pointerBeforeReferenceNode;
}

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

console.log(logAnchor(it));
it.nextNode();
console.log(logAnchor(it));

DIV before=true
SPAN before=false

🚀 Common Use Cases

• Inspect where a NodeIterator is anchored during debugging.
• Read properties from the current anchor node mid-walk.
• Verify the walk root matches referenceNode on create.
• Pair with pointerBeforeReferenceNode for full position state.
• Understand iterator behavior when the DOM is mutated during traversal.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since April 2018) — no Deprecated / Experimental / Non-standard banner.
• referenceNode is read-only; movement methods update it.
• Do not confuse with iterator.root (the original walk root).
• MDN: iterator stays anchored to referenceNode as nodes are inserted.
• Related learning: pointerBeforeReferenceNode, filter, childNodes.

💡 Best Practices