Document: createNodeIterator() method

The Document.createNodeIterator() method returns a new NodeIterator object.

Syntax

js
createNodeIterator(root)
createNodeIterator(root, whatToShow)
createNodeIterator(root, whatToShow, filter)

Parameters

root

The root node at which to begin the NodeIterator's traversal.

whatToShow Optional

An optional 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 SHOW_ALL constant.

Constant Numerical value Description
NodeFilter.SHOW_ALL 4294967295 (that is the max value of unsigned long) Shows all nodes.
NodeFilter.SHOW_ATTRIBUTE Deprecated 2 Shows attribute Attr nodes. This is meaningful only when creating a TreeWalker with an Attr node as its root. In this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.
NodeFilter.SHOW_CDATA_SECTION Deprecated 8 Shows CDATASection nodes.
NodeFilter.SHOW_COMMENT 128 Shows Comment nodes.
NodeFilter.SHOW_DOCUMENT 256 Shows Document nodes.
NodeFilter.SHOW_DOCUMENT_FRAGMENT 1024 Shows DocumentFragment nodes.
NodeFilter.SHOW_DOCUMENT_TYPE 512 Shows DocumentType nodes.
NodeFilter.SHOW_ELEMENT 1 Shows Element nodes.
NodeFilter.SHOW_ENTITY Deprecated 32 Legacy, no more usable.
NodeFilter.SHOW_ENTITY_REFERENCE Deprecated 16 Legacy, no more usable.
NodeFilter.SHOW_NOTATION Deprecated 2048 Legacy, no more usable.
NodeFilter.SHOW_PROCESSING_INSTRUCTION 64 Shows ProcessingInstruction nodes.
NodeFilter.SHOW_TEXT 4 Shows Text nodes.
filter Optional

A callback function or an object with an acceptNode() method. 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. The method should return one of NodeFilter.FILTER_ACCEPT, NodeFilter.FILTER_REJECT, or NodeFilter.FILTER_SKIP. See the Example.

For createNodeIterator, the values NodeFilter.FILTER_REJECT and NodeFilter.FILTER_SKIP are equivalent. This node will not be included in the list of iterable nodes, but its children will continue to be iterated over.

Return value

A new NodeIterator object.

Examples

js
const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  (node) =>
    node.nodeName.toLowerCase() === "p"
      ? NodeFilter.FILTER_ACCEPT
      : NodeFilter.FILTER_REJECT,
);
const pars = [];
let currentNode;

while ((currentNode = nodeIterator.nextNode())) {
  pars.push(currentNode);
}

The same, but using an object with an acceptNode() method:

js
const nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT,
  {
    acceptNode(node) {
      return node.nodeName.toLowerCase() === "p"
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT;
    },
  },
);
const pars = [];
let currentNode;

while ((currentNode = nodeIterator.nextNode())) {
  pars.push(currentNode);
}

Specifications

Specification
DOM Standard
# dom-document-createnodeiterator

Browser compatibility

BCD tables only load in the browser