JavaScript NodeIterator whatToShow Property

What You’ll Learn

The whatToShow property of a NodeIterator returns a read-only bitmask of node types the iterator will consider. Learn how it mirrors the second argument to createNodeIterator, how NodeFilter.SHOW_ELEMENT and SHOW_TEXT change what you see, and how it works with filter—with five examples and try-it labs.

Introduction

When you call document.createNodeIterator(root, whatToShow, filter), the second argument tells the browser which node types to include in the walk—elements, text nodes, comments, and more. The iterator stores that value on its read-only whatToShow property.

Think of whatToShow as a coarse pre-filter. It runs before your custom filter acceptNode() logic. If a node type is not in the bitmask, the iterator skips it entirely.

Understanding the whatToShow Property

A read-only instance property on NodeIterator that returns a non-negative integer representing a bitmask of NodeFilter constants.

• Returns — an unsigned long (bitmask).
• Read-only — set at creation, never changes.
• Source — second argument to createNodeIterator.
• Combine flags — use bitwise OR, e.g. SHOW_ELEMENT | SHOW_TEXT.
• Default — NodeFilter.SHOW_ALL when omitted.
• Baseline Widely available on MDN (since July 2015).

Common NodeFilter constants

📝 Syntax

Read the property on a NodeIterator:

nodeIterator.whatToShow

Return value

A non-negative integer bitmask. See document.createNodeIterator() for the full list of flags.

Typical pattern (MDN idea)

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

if (
  nodeIterator.whatToShow & NodeFilter.SHOW_ALL ||
  nodeIterator.whatToShow & NodeFilter.SHOW_COMMENT
) {
  // iterator may visit comment nodes
}

⚖️ whatToShow vs Related Ideas

Examples Gallery

Examples follow MDN NodeIterator.whatToShow. Labs show how the bitmask controls which node types appear during a walk.

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

console.log(it.whatToShow === NodeFilter.SHOW_ELEMENT); // true

true

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

const itEl = document.createNodeIterator(box, NodeFilter.SHOW_ELEMENT);
const itText = document.createNodeIterator(box, NodeFilter.SHOW_TEXT);

const elNames = [];
let n;
while ((n = itEl.nextNode())) elNames.push(n.nodeName);

const textValues = [];
while ((n = itText.nextNode())) textValues.push(n.nodeValue.trim());

console.log(elNames);    // ["DIV", "SPAN", "SPAN"]
console.log(textValues); // ["Hello", "World"]

["DIV","SPAN","SPAN"]
["Hello","World"]

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

console.log(it.whatToShow === NodeFilter.SHOW_ALL); // true

true

const mask =
  NodeFilter.SHOW_ELEMENT |
  NodeFilter.SHOW_COMMENT |
  NodeFilter.SHOW_TEXT;

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

console.log(nodeIterator.whatToShow === mask); // true

true

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

const showsComments =
  (nodeIterator.whatToShow & NodeFilter.SHOW_ALL) ||
  (nodeIterator.whatToShow & NodeFilter.SHOW_COMMENT);

console.log(showsComments); // true

true

🚀 Common Use Cases

• Walk only element nodes and skip text noise with SHOW_ELEMENT.
• Extract text content with SHOW_TEXT inside a subtree.
• Include HTML comments in a walk with SHOW_COMMENT.
• Inspect an iterator’s mask when debugging third-party code.
• Pair a coarse whatToShow mask with a fine filter.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• whatToShow is read-only and fixed for the iterator’s lifetime.
• Use bitwise OR to combine multiple NodeFilter constants.
• Do not confuse with filter, which adds custom accept/reject logic.
• Related learning: root, filter, childNodes.

💡 Best Practices