JavaScript Document createTreeWalker() Method

What You’ll Learn

document.createTreeWalker() is an instance method that returns a TreeWalker for walking a DOM subtree (see MDN Document: createTreeWalker()). Learn root, whatToShow, custom filters, nextNode() loops, tree moves like firstChild, how it compares to NodeIterator, and five try-it labs.

Introduction

A TreeWalker is a cursor for a DOM branch. You pick a root, optionally filter which node types matter, then move with nextNode() — or step like a real tree using firstChild(), nextSibling(), and friends.

document.createTreeWalker(root, whatToShow, filter) builds that walker. MDN’s first example walks every text node under #root and uppercases node.data.

For simple element lists, querySelectorAll is often enough. Use TreeWalker when you need text/comment traversal or parent/sibling navigation.

Related tutorials: createNodeIterator(), nodeType, createTextNode().

Understanding document.createTreeWalker()

An instance method on the page’s document object (MDN Document interface).

• root — node representing the walker root; initial TreeWalker.currentNode (MDN).
• whatToShow — optional bitmask of NodeFilter show constants; default SHOW_ALL (MDN).
• filter — optional callback or object with acceptNode() (MDN).
• Return value — a new TreeWalker (MDN).
• Document order — nextNode() / previousNode().
• Tree moves — parentNode, firstChild, lastChild, previousSibling, nextSibling.

📝 Syntax

General forms of Document.createTreeWalker (MDN):

createTreeWalker(root)
createTreeWalker(root, whatToShow)
createTreeWalker(root, whatToShow, filter)

Parameters

• root — a Node that is the root of the TreeWalker and the initial currentNode (MDN).
• whatToShow (optional) — unsigned long bitmask from NodeFilter constants. Defaults to 0xFFFFFFFF ((SHOW_ALL) (MDN).
• filter (optional) — callback or { acceptNode() } returning FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP (MDN).

Return value

A new TreeWalker object (MDN).

Filter return values (MDN)

• FILTER_ACCEPT — include this node.
• FILTER_REJECT — exclude this node and its subtree.
• FILTER_SKIP — exclude this node only (descendants may still be visited).

Useful whatToShow flags

Combine flags with |, for example NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT. MDN: SHOW_ATTRIBUTE is only useful when the root is an Attr node — prefer Element.attributes for attributes. Some older constants (SHOW_ENTITY, …) are legacy and no longer effective.

MDN example (whatToShow)

const treeWalker = document.createTreeWalker(
  document.querySelector("#root"),
  NodeFilter.SHOW_TEXT,
);

while (treeWalker.nextNode()) {
  const node = treeWalker.currentNode;
  node.data = node.data.toUpperCase();
}

⚖️ TreeWalker vs NodeIterator vs querySelectorAll

Examples Gallery

Examples follow MDN Document: createTreeWalker() and practical TreeWalker patterns for beginners.

const treeWalker = document.createTreeWalker(
  document.querySelector("#root"),
  NodeFilter.SHOW_TEXT,
);

while (treeWalker.nextNode()) {
  const node = treeWalker.currentNode;
  node.data = node.data.toUpperCase();
}

console.log(document.querySelector("#root").textContent);

THIS IS A TEXT NODE.
AND THIS IS A SPAN ELEMENT.

const root = document.querySelector("#demo");
const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
const tags = [];

while (walker.nextNode()) {
  tags.push(walker.currentNode.tagName.toLowerCase());
}

console.log(tags.join(", "));

ul, li, li, strong

const root = document.querySelector("#list");
const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);

const first = walker.firstChild(); // first matching child of root
const names = [];
let node = first;
while (node) {
  names.push(node.tagName.toLowerCase());
  node = walker.nextSibling();
}

console.log(names.join(", "));

li, li, li

const walker = document.createTreeWalker(
  document.querySelector("#box"),
  NodeFilter.SHOW_ELEMENT,
  (node) => {
    if (node.classList.contains("skip-branch")) {
      return NodeFilter.FILTER_REJECT; // skip node + subtree
    }
    if (node.classList.contains("keep")) {
      return NodeFilter.FILTER_ACCEPT;
    }
    return NodeFilter.FILTER_SKIP; // skip wrapper, still visit children
  },
);

const kept = [];
while (walker.nextNode()) {
  kept.push(walker.currentNode.id || walker.currentNode.tagName);
}
console.log(kept.join(", "));

a, c

const root = document.querySelector("#sample");

function collectText(factory) {
  const cursor = factory(root, NodeFilter.SHOW_TEXT);
  const parts = [];
  while (cursor.nextNode()) {
    const t = cursor.currentNode.data.trim();
    if (t) parts.push(t);
  }
  return parts.join(" | ");
}

console.log("walker:", collectText(document.createTreeWalker.bind(document)));
console.log("iterator:", collectText(document.createNodeIterator.bind(document)));

walker: Hello | World
iterator: Hello | World

🚀 Common Use Cases

• Transform all text — MDN uppercase / encodeURI patterns.
• Find comments or mixed node types — selectors cannot see comments.
• Skip whole branches — FILTER_REJECT on a container.
• Sibling navigation — walk only direct matching children.
• Editors / highlighters — walk text nodes under a contenteditable root.
• Teaching the DOM tree — contrast flat iterators with tree moves.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• Returns a TreeWalker; currentNode starts at root (MDN).
• FILTER_REJECT skips a whole subtree; FILTER_SKIP skips one node (MDN).
• SHOW_ATTRIBUTE is special — prefer Element.attributes (MDN).
• Some older show constants are legacy and no longer effective (MDN).
• Related: createNodeIterator(), nodeType, createTextNode().

💡 Best Practices