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
```

div {
  margin: 0.25em 0;
  padding: 0.25em;
}
span {
  display: inline-block;
}
```



```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 with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `TreeWalker`: Related interface