unist-util-visit

unist-util-visit is a small, focused utility from the unified/syntax-tree collective for walking unist abstract syntax trees such as mdast (Markdown), hast (HTML), and nlcst (natural language). It performs depth-first traversal and calls a visitor function for every node, or only for nodes matching a unist-util-is compatible test.

The visitor receives each node along with its index and parent, and can inspect, mutate, skip subtrees, or stop the walk entirely by returning control actions. It is one of the most widely depended-on building blocks in the remark, rehype, and retext plugin ecosystems.

What You Get

• A single visit(tree[, test], visitor[, reverse]) function that covers the common tree-walking use case
• Control actions CONTINUE, SKIP, and EXIT to steer or stop traversal from inside the visitor
• unist-util-is compatible tests so you can target nodes by type, property, or predicate function
• Rich TypeScript types that infer the concrete node and parent types for a given tree and test
• ESM-only, dependency-light package that works in Node.js, Deno, and browsers via esm.sh

Common Use Cases

• Writing remark, rehype, or retext plugins that transform Markdown, HTML, or prose syntax trees
• Collecting or rewriting specific node types (links, headings, images, text) across a document
• Mutating a tree in place - removing, replacing, or reordering nodes during a single walk
• Extracting data such as all headings or code blocks for tables of contents or indexes

Under The Hood

Architecture

The entire runtime lives in lib/index.js, where the exported visit function is a thin ergonomic wrapper around visitParents from the sibling unist-util-visit-parents package. visit first normalizes its overloaded arguments - detecting whether the second argument is a visitor or a unist-util-is test and whether the third is a visitor or the reverse flag - then delegates the actual depth-first traversal to visitParents. It adapts the parents-stack callback signature into the friendlier (node, index, parent) shape by taking the last element of the parents array as parent and computing index via parent.children.indexOf(node). The CONTINUE, EXIT, and SKIP action constants are simply re-exported from the parents package. index.js at the root re-exports the public runtime and the types live in index.d.ts.

Tech Stack

This is pure ESM JavaScript ("type": "module", single "exports": "./index.js") authored with JSDoc and compiled to .d.ts declarations via the TypeScript compiler. Runtime dependencies are minimal: @types/unist, unist-util-is, and unist-util-visit-parents. Development tooling includes c8 for coverage, tsd and type-coverage for type checking, and xo/prettier/remark for linting and formatting. It targets Node.js 16 and up.

Code Quality

Quality is exemplary for a micro-utility. A dedicated test.js suite exercises the API and the build enforces 100% code coverage (c8 --100) and 100% type coverage (typeCoverage.atLeast: 100, strict). The source is densely annotated with JSDoc, including elaborate conditional-type machinery that infers which nodes reach the visitor and what their parents can be. Naming is consistent with the wider syntax-tree ecosystem and error handling is unnecessary given the pure, side-effect-free traversal design.

API Design

The public surface is deliberately tiny: one visit function plus three action constants. Function overloads make the test argument optional while preserving precise types, so a visitor for 'text' nodes is typed as receiving a text node. The README documents every export and type thoroughly, and getting started requires almost no boilerplate - import visit, pass a tree and a callback. This minimalism and strong typing are why it underpins so much of the unified ecosystem.