Document: createTreeWalker() method

The Document.createTreeWalker() creator method returns a newly created TreeWalker object.

Syntax

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

Parameters

root

A Node representing the root of the TreeWalker object, which is the initial value of TreeWalker.currentNode.

whatToShow Optional

An unsigned long representing a bitmask created by combining the constant properties of NodeFilter. It is a convenient way of filtering for certain types of node. It defaults to 0xFFFFFFFF, representing the NodeFilter.SHOW_ALL constant.

Constant Numerical value Description
NodeFilter.SHOW_ALL 0xFFFFFFFF Shows all nodes.
NodeFilter.SHOW_ATTRIBUTE 0x2 Shows Attr nodes.
NodeFilter.SHOW_CDATA_SECTION 0x8 Shows CDATASection nodes.
NodeFilter.SHOW_COMMENT 0x80 Shows Comment nodes.
NodeFilter.SHOW_DOCUMENT 0x100 Shows Document nodes.
NodeFilter.SHOW_DOCUMENT_FRAGMENT 0x400 Shows DocumentFragment nodes.
NodeFilter.SHOW_DOCUMENT_TYPE 0x200 Shows DocumentType nodes.
NodeFilter.SHOW_ELEMENT 0x1 Shows Element nodes.
NodeFilter.SHOW_ENTITY Deprecated 0x20 Legacy, no longer effective.
NodeFilter.SHOW_ENTITY_REFERENCE Deprecated 0x10 Legacy, no longer effective.
NodeFilter.SHOW_NOTATION Deprecated 0x800 Legacy, no longer effective.
NodeFilter.SHOW_PROCESSING_INSTRUCTION 0x40 Shows ProcessingInstruction nodes.
NodeFilter.SHOW_TEXT 0x4 Shows Text nodes.

Note: Since the parent of any Attr node is always null, TreeWalker.nextNode() and TreeWalker.previousNode() will never return an Attr node. To traverse Attr nodes, use Element.attributes instead.

filter Optional

A callback function or an object with an acceptNode() method, which returns NodeFilter.FILTER_ACCEPT, NodeFilter.FILTER_REJECT, or NodeFilter.FILTER_SKIP. The function or method will be called for each node in the subtree based at root which is accepted as included by the whatToShow flag to determine whether or not to include it in the list of iterable nodes:

  • If the return value is NodeFilter.FILTER_ACCEPT, this node is included.
  • If the return value is NodeFilter.FILTER_REJECT, any node in the subtree based at this node is not included.
  • If the return value is NodeFilter.FILTER_SKIP, this node is not included.

Return value

A new TreeWalker object.

Examples

Using whatToShow

This example uses whatToShow to transform text contents into upper case. Note that the text nodes of the descendants of the #root element are also traversed despite of the fact that they are not child nodes of the #root element.

HTML

html
<div id="root">
  This is a text node.
  <span>And this is a <code>span</code> element.</span>
</div>

CSS

css
span {
  background-color: aqua;
}

JavaScript

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

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

Result

Using filter

This example uses filter to escape text contents. For any text node, its content will be escaped using encodeURI() if it is a descendant of an .escape element but not of any .no-escape element.

HTML

html
<div>
  <div>
    This is not escaped. <span class="escape">But this is escaped.</span>
  </div>
  <div class="escape">This is escaped.</div>
  <div class="no-escape">This is not escaped.</div>
</div>
<hr />
<div class="escape">
  <div>
    This is escaped. <span class="no-escape">But this is not escaped.</span>
  </div>
  <div class="no-escape">This is not escaped.</div>
</div>
<hr />
<div class="no-escape">
  <div>This is not escaped.</div>
  <div class="escape">This is not escaped.</div>
</div>

CSS

css
.escape {
  border: dashed;
}
.no-escape {
  border: solid;
}

JavaScript

js
const treeWalker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  (node) =>
    node.classList.contains("no-escape")
      ? NodeFilter.FILTER_REJECT
      : node.closest(".escape")
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_SKIP,
);

while (treeWalker.nextNode()) {
  for (const node of treeWalker.currentNode.childNodes) {
    if (node.nodeType === Node.TEXT_NODE && /\S/.test(node.data)) {
      // Exclude whitespace-only text nodes
      node.data = encodeURI(node.data.replace(/\s+/g, " "));
    }
  }
}

Result

Specifications

Specification
DOM Standard
# dom-document-createtreewalker

Browser compatibility

BCD tables only load in the browser

See also