Unist Util Visit

https://github.com/syntax-tree/unist-util-visit
Admin
Unist Util Visit is a utility library for walking and traversing Abstract Syntax Tree (AST) nodes in...
Tokens:4,056
Snippets:38
Trust Score:9.7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install unist-util-visit with npm

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Install this package using npm. It is ESM only and requires Node.js version 16 or higher.

```sh
npm install unist-util-visit
```

--------------------------------

### Example output of visiting a Markdown AST

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

This shows the expected output when visiting text nodes in a Markdown AST.

```js
["Some ", "paragraph"]
[ "emphasis", "emphasis" ]
[ ", ", "paragraph" ]
[ "strong", "strong" ]
[ ", and ", "paragraph" ]
[ ".", "paragraph" ]
```

--------------------------------

### Use unist-util-visit to traverse a Markdown AST

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

This example demonstrates how to use `visit` to traverse a Markdown AST generated by `mdast-util-from-markdown`. It logs the node value and its parent's type for each text node.

```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {visit} from 'unist-util-visit'

const tree = fromMarkdown('Some *emphasis*, **strong**, and `code`.')

visit(tree, 'text', function (node, index, parent) {
  console.log([node.value, parent ? parent.type : index])
})
```

--------------------------------

### Inferring Visitor Signatures with BuildVisitor (TypeScript)

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

BuildVisitor is a TypeScript utility type that infers a fully-typed visitor function signature from a tree type and an optional test. Use it to get narrowed node, index, and parent types.

```typescript
import type { Root } from 'mdast'
import type { BuildVisitor } from 'unist-util-visit'
import { visit } from 'unist-util-visit'

// Infer a visitor for all nodes in an mdast Root tree
type AnyVisitor = BuildVisitor<Root>

// Infer a visitor specifically for 'heading' nodes
type HeadingVisitor = BuildVisitor<Root, 'heading'>

const myVisitor: HeadingVisitor = function (node, index, parent) {
  // node  → Heading (with .depth, .children, etc.)
  // index → number | undefined
  // parent → Blockquote | FootnoteDefinition | ListItem | Root | undefined
  console.log('Heading depth:', node.depth)
}

const tree: Root = {
  type: 'root',
  children: [
    { type: 'heading', depth: 2, children: [{ type: 'text', value: 'Hi' }] }
  ]
}

visit(tree, 'heading', myVisitor)
```

--------------------------------

### Import unist-util-visit in the browser

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Import the necessary functions from unist-util-visit in the browser using esm.sh with bundling.

```html
<script type="module">
  import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5?bundle'
</script>
```

--------------------------------

### Import unist-util-visit in Deno

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Import the necessary functions from unist-util-visit in Deno using esm.sh.

```js
import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5'
```

--------------------------------

### visit(tree[, test], visitor[, reverse])

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Walks the unist tree. It accepts a tree, an optional test to filter nodes, a visitor function to process matching nodes, and an optional reverse flag to traverse in reverse.

```APIDOC
## visit(tree[, test], visitor[, reverse])

### Description
Walks the unist tree. It accepts a tree, an optional test to filter nodes, a visitor function to process matching nodes, and an optional reverse flag to traverse in reverse.

### Parameters
#### Path Parameters
- **tree** (unist-node) - Required - The unist tree to walk.
- **test** (unist-is compatible test or string or array of strings or object or function) - Optional - A test to filter nodes. If not provided, all nodes are visited.
- **visitor** (Visitor) - Required - The function to call for each matching node.
- **reverse** (boolean) - Optional - If true, traverse the tree in reverse.

### Visitor Function Signature
`visitor(node, index, parent)`

- **node** (unist-node) - The current node being visited.
- **index** (number or undefined) - The index of the node in its parent.
- **parent** (unist-node or undefined) - The parent of the current node.

### Return Value
The visitor function can return one of the following:
- `CONTINUE` (or `true`): Continue traversing as normal.
- `EXIT` (or `false`): Stop traversing immediately.
- `SKIP` (or `'skip'`): Do not traverse this node's children.
- `[CONTINUE, index]` (or `[true, index]`): Continue traversing and move to the sibling at `index` next.
- `[SKIP, index]` (or `['skip', index]`): Do not traverse this node's children and move to the sibling at `index` next.

### Example
```js
import {visit} from 'unist-util-visit'

visit(tree, 'text', function (node, index, parent) {
  console.log([node.value, parent ? parent.type : index])
})
```
```

--------------------------------

### Visit All Nodes in a UNIST Tree

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Logs the type, index, and parent of every node in a UNIST tree. Requires importing `fromMarkdown` and `visit`.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { CONTINUE, EXIT, SKIP, visit } from 'unist-util-visit'

const tree = fromMarkdown('# Hello\n\nSome _emphasis_ and **strong** text.')

// 1. Visit ALL nodes (no test) — log every node type
visit(tree, function (node, index, parent) {
  console.log(node.type, '@ index', index, 'inside', parent?.type ?? 'N/A')
})
// root @ index undefined inside N/A
// heading @ index 0 inside root
// text @ index 0 inside heading
// paragraph @ index 1 inside root
// text @ index 0 inside paragraph
// emphasis @ index 1 inside paragraph
// text @ index 0 inside emphasis
// text @ index 2 inside paragraph
// strong @ index 3 inside paragraph
// text @ index 0 inside strong
// text @ index 4 inside paragraph

// 2. Visit only 'text' nodes using a string test
const textValues = []
visit(tree, 'text', function (node) {
  textValues.push(node.value)
})
console.log(textValues)
// [ 'Hello', 'Some ', 'emphasis', ' and ', 'strong', ' text.' ]

// 3. Visit multiple node types using an array test
visit(tree, ['emphasis', 'strong'], function (node) {
  console.log(node.type) // 'emphasis', then 'strong'
})

// 4. Visit using a property/partial-object test
visit(tree, { depth: 1 }, function (node) {
  console.log(node.type, node.depth) // 'heading' 1
})

// 5. Visit using a custom predicate function
visit(tree, (node) => node.type === 'text' && 'value' in node && node.value.length > 3, function (node) {
  console.log(node.value) // 'Hello', 'Some ', 'emphasis', ' and ', 'strong', ' text.'
})

// 6. Reverse traversal (NRL)
const reverseOrder = []
visit(tree, 'text', function (node) {
  reverseOrder.push(node.value)
}, true /* reverse */)
console.log(reverseOrder)
// [ ' text.', 'strong', ' and ', 'emphasis', 'Some ', 'Hello' ]
```

--------------------------------

### CONTINUE

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Constant to indicate that traversal should continue as normal.

```APIDOC
## CONTINUE

### Description
Constant to indicate that traversal should continue as normal.

### Type
`boolean` (value is `true`)
```

--------------------------------

### CONTINUE

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Signals the visitor to continue traversal as normal. This is the default behavior when a visitor returns `undefined`.

```APIDOC
## CONTINUE

### Description
Signals the visitor to continue traversal as normal. This is the default behavior when a visitor returns `undefined`.

### Request Example
```js
import { fromMarkdown } from 'mdast-util-from-markdown'
import { CONTINUE, visit } from 'unist-util-visit'

const tree = fromMarkdown('Hello _world_ and **earth**.')

const collected = []

visit(tree, function (node) {
  if (node.type === 'text') {
    collected.push(node.value)
  }
  return CONTINUE // explicitly continue (same as returning undefined)
})

console.log(collected)
```
```

--------------------------------

### EXIT

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Constant to indicate that traversal should stop immediately.

```APIDOC
## EXIT

### Description
Constant to indicate that traversal should stop immediately.

### Type
`boolean` (value is `false`)
```

--------------------------------

### EXIT

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Immediately stops the entire tree traversal when returned from a visitor. Useful for finding the first match.

```APIDOC
## EXIT

### Description
Immediately stops the entire tree traversal when returned from a visitor. Useful for finding the first match.

### Request Example
```js
import { fromMarkdown } from 'mdast-util-from-markdown'
import { EXIT, visit } from 'unist-util-visit'

const tree = fromMarkdown('First _emphasis_ here. Second _emphasis_ there.')

let firstEmphasisText = null

visit(tree, 'emphasis', function (node) {
  // Grab the text inside the first emphasis node, then stop walking
  firstEmphasisText = node.children[0].value
  return EXIT
})

console.log(firstEmphasisText)
```
```

--------------------------------

### SKIP

Source: https://github.com/syntax-tree/unist-util-visit/blob/main/readme.md

Constant to indicate that traversal should skip the children of the current node.

```APIDOC
## SKIP

### Description
Constant to indicate that traversal should skip the children of the current node.

### Type
`string` (value is `'skip'`)
```

--------------------------------

### Control Traversal with Numeric Index

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Return a numeric index from a visitor to control the next sibling visited. Returning 0 restarts traversal from the first child, and returning parent.children.length skips remaining siblings.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { visit } from 'unist-util-visit'

const tree = fromMarkdown('Alpha. Beta. Gamma.')

let patchedOnce = false

visit(tree, 'text', function (node, index, parent) {
  // The first time we see a text node, inject a new sibling before index 1
  // then return index 0 to re-process from the start
  if (!patchedOnce && parent && index === 0) {
    patchedOnce = true
    parent.children.splice(1, 0, { type: 'text', value: '(inserted)' })
    return 0 // restart from index 0 to visit the inserted node
  }
  console.log('visiting text:', node.value)
})
```

--------------------------------

### In-place Tree Transformation with Sibling Insertion/Removal

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Visitors can mutate nodes directly. When removing or inserting siblings before the current node, return the correct new index to maintain consistent traversal. Use SKIP to avoid descending into subtrees.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { toMarkdown } from 'mdast-util-to-markdown'
import { SKIP, visit } from 'unist-util-visit'

// Unwrap all emphasis nodes — replace each <em> with its children inline
const tree = fromMarkdown('Hello _world_ and _there_!')

visit(tree, 'emphasis', function (node, index, parent) {
  if (typeof index === 'number' && parent) {
    // Replace the emphasis node with its children
    parent.children.splice(index, 1, ...node.children)
    // Return the same index so the first injected child is not skipped
    return [SKIP, index]
  }
})

console.log(toMarkdown(tree))
```

--------------------------------

### Continue Traversal with CONTINUE

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Explicitly signals to continue tree traversal. This is the default behavior and equivalent to returning `undefined`.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { CONTINUE, visit } from 'unist-util-visit'

const tree = fromMarkdown('Hello _world_ and **earth**.')

const collected = []

visit(tree, function (node) {
  if (node.type === 'text') {
    collected.push(node.value)
  }
  return CONTINUE // explicitly continue (same as returning undefined)
})

console.log(collected)
// [ 'Hello ', 'world', ' and ', 'earth', '.' ]
```

--------------------------------

### Stop Traversal Immediately with EXIT

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Immediately stops the entire tree traversal when returned from a visitor. Useful for finding the first matching node.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { EXIT, visit } from 'unist-util-visit'

const tree = fromMarkdown('First _emphasis_ here. Second _emphasis_ there.')

let firstEmphasisText = null

visit(tree, 'emphasis', function (node) {
  // Grab the text inside the first emphasis node, then stop walking
  firstEmphasisText = node.children[0].value
  return EXIT
})

console.log(firstEmphasisText)
// 'emphasis'
```

--------------------------------

### SKIP

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Prevents the visitor from descending into the current node's children, while continuing traversal of siblings.

```APIDOC
## SKIP

### Description
Prevents the visitor from descending into the current node's children, while continuing traversal of siblings.

### Request Example
```js
import { fromMarkdown } from 'mdast-util-from-markdown'
import { SKIP, visit } from 'unist-util-visit'

const tree = fromMarkdown('Text _emphasis **nested**_ and `code`.')

const visited = []

visit(tree, function (node) {
  visited.push(node.type)

  // Don't recurse into emphasis nodes — skip their children
  if (node.type === 'emphasis') {
    return SKIP
  }
})

console.log(visited)
```
```

--------------------------------

### Skip Children with SKIP

Source: https://context7.com/syntax-tree/unist-util-visit/llms.txt

Prevents the visitor from descending into the current node's children, while continuing traversal of siblings. Useful for avoiding traversal into specific node types.

```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import { SKIP, visit } from 'unist-util-visit'

const tree = fromMarkdown('Text _emphasis **nested**_ and `code`.')

const visited = []

visit(tree, function (node) {
  visited.push(node.type)

  // Don't recurse into emphasis nodes — skip their children
  if (node.type === 'emphasis') {
    return SKIP
  }
})

console.log(visited)
// [ 'root', 'paragraph', 'text', 'emphasis', 'inlineCode', 'text' ]
// Note: 'strong' and its inner 'text' inside emphasis are never visited
```
Tokens:
Raw