JavaScript NodeIterator filter Property

What You’ll Learn

The filter property of a NodeIterator returns the NodeFilter object used to screen nodes during traversal. Learn how acceptNode() chooses FILTER_ACCEPT or FILTER_REJECT, how it relates to document.createNodeIterator(), and how to walk nodes with nextNode()—with five examples and try-it labs.

Introduction

A NodeIterator walks a DOM subtree in document order. When you create one with document.createNodeIterator(root, whatToShow, filter), the third argument is a filter object. The iterator stores that object on its read-only filter property.

The filter’s acceptNode(node) method runs on candidate nodes. Return NodeFilter.FILTER_ACCEPT to include a node in the walk, or NodeFilter.FILTER_REJECT to skip it.

Understanding the filter Property

A read-only instance property on NodeIterator that exposes the NodeFilter passed when the iterator was created.

• Returns — a NodeFilter object with acceptNode(node).
• Read-only — you cannot assign a new filter after creation.
• acceptNode — called for nodes that pass the whatToShow bitmask.
• FILTER_ACCEPT — node is included when you call nextNode().
• FILTER_REJECT — node is skipped (on NodeIterator, same as FILTER_SKIP).
• Baseline Widely available on MDN (since July 2015).

📝 Syntax

Read the property on a NodeIterator:

nodeIterator.filter

Return value

A NodeFilter object (the one passed to createNodeIterator).

Typical pattern (MDN idea)

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

const nodeFilter = nodeIterator.filter;
// same object passed as the third argument

⚖️ filter vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.filter and Document.createNodeIterator().

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

const nodeFilter = nodeIterator.filter;
console.log(typeof nodeFilter.acceptNode); // "function"

function

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

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

["First paragraph", "Second paragraph"]

const iterator = document.createNodeIterator(
  document.getElementById("box"),
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return node.classList.contains("skip")
        ? NodeFilter.FILTER_REJECT
        : NodeFilter.FILTER_ACCEPT;
    },
  },
);

Keep
Also keep

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

const target = document.querySelector("h1");
const result = iterator.filter.acceptNode(target);
console.log(result === NodeFilter.FILTER_ACCEPT); // true

true

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

const labels = [];
let item;
while ((item = iterator.nextNode())) {
  labels.push(item.textContent);
}

Apple
Banana
Cherry

🚀 Common Use Cases

• Inspect the filter object after creating a NodeIterator.
• Accept only certain tag names or roles during document-order walks.
• Skip hidden or disabled nodes with custom acceptNode logic.
• Debug filtering by calling iterator.filter.acceptNode(node) on one node.
• Pair with nextNode() to collect nodes that pass both whatToShow and filter.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• filter is read-only; define rules when calling createNodeIterator.
• On NodeIterator, FILTER_REJECT and FILTER_SKIP are equivalent.
• The filter can be a function or an object with acceptNode (MDN accepts both for the third parameter).
• Related learning: NodeList.forEach(), childNodes, NodeList.length.

💡 Best Practices