JavaScript NodeIterator pointerBeforeReferenceNode Property

What You’ll Learn

The pointerBeforeReferenceNode property of a NodeIterator is a read-only boolean that tells you whether the walk pointer sits before or after the anchor (referenceNode). Learn what true and false mean, how nextNode() updates the flag, and how to pair it with filter—with five examples and try-it labs.

Introduction

A NodeIterator does not only return nodes from nextNode()—it also tracks where the walk is anchored. The read-only pointerBeforeReferenceNode property answers a simple question: is the iterator pointer immediately before the reference node, or immediately after it?

MDN’s idea: after you create an iterator, read nodeIterator.pointerBeforeReferenceNode to inspect that flag. As you call nextNode() or previousNode(), both this boolean and referenceNode can change.

Understanding the pointerBeforeReferenceNode Property

A read-only instance property on NodeIterator that describes iterator position relative to the anchor node.

• Returns — a boolean.
• true — pointer is before referenceNode.
• false — pointer is after referenceNode.
• Read-only — updated by iterator movement, not by assignment.
• Baseline Widely available on MDN (since April 2018).

📝 Syntax

Read the property on a NodeIterator:

nodeIterator.pointerBeforeReferenceNode

Return value

A boolean: true (before anchor) or false (after anchor).

Typical pattern (MDN idea)

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

const flag = nodeIterator.pointerBeforeReferenceNode;
// true or false depending on anchor position

⚖️ pointerBeforeReferenceNode vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.pointerBeforeReferenceNode. Labs show how the flag changes as you walk the tree.

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

console.log(nodeIterator.pointerBeforeReferenceNode);
// often true before the first nextNode()

true

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

console.log("before", it.pointerBeforeReferenceNode);
it.nextNode();
console.log("after", it.pointerBeforeReferenceNode);

before true
after false

function logState(it, label) {
  console.log(
    label,
    it.referenceNode.nodeName,
    it.pointerBeforeReferenceNode,
  );
}

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

logState(it, "start");
it.nextNode();
logState(it, "step1");

start DIV true
step1 SPAN false

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

it.nextNode();
console.log("after next", it.pointerBeforeReferenceNode);
it.previousNode();
console.log("after previous", it.pointerBeforeReferenceNode);

after next false
after previous true

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(node.textContent + " " + it.pointerBeforeReferenceNode);
}

Apple false
Banana false
Cherry false

🚀 Common Use Cases

• Debug iterator position during complex DOM walks.
• Inspect anchor state alongside referenceNode.
• Verify whether the pointer is before or after the current anchor.
• Learn how nextNode() and previousNode() move the walk.
• Build advanced traversal tools that depend on exact iterator state.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since April 2018) — no Deprecated / Experimental / Non-standard banner.
• Read-only boolean; movement methods update it.
• Works together with referenceNode to describe iterator state.
• Most simple loops only need nextNode(); this property is for position awareness.
• Related learning: filter, NodeList.forEach(), childNodes.

💡 Best Practices