# JSON Tree View

URL: https://ark-ui.com/docs/utilities/json-tree-view
LLM: https://ark-ui.com/llms.txt/utilities/json-tree-view

A component that displays JSON data in an interactive, collapsible tree structure.

---



## Anatomy

To set up the JSON tree view correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.



## Examples

Learn how to use the `JsonTreeView` component in your project. Let's take a look at the most basic example:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

export const Basic = () => {
  return (
    <JsonTreeView.Root
      defaultExpandedDepth={1}
      className={styles.Root}
      data={{
        name: 'John Doe',
        age: 30,
        email: 'john.doe@example.com',
        tags: ['tag1', 'tag2', 'tag3'],
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Different Data Types

The JSON tree view can display various JavaScript data types including objects, arrays, primitives, and special values:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

const testArray = [1, 2, 3, 4, 5]
Object.defineProperties(testArray, {
  customProperty: { value: 'custom value', enumerable: false, writable: false },
  anotherProperty: { value: 42, enumerable: false, writable: false },
})

export const ArrayData = () => {
  return (
    <JsonTreeView.Root
      defaultExpandedDepth={1}
      className={styles.Root}
      data={{
        normalArray: [1, 2, 3],
        arrayWithNonEnumerableProperties: testArray,
        sparseArray: (() => {
          const sparse = []
          sparse[0] = 'first'
          sparse[5] = 'sixth'
          return sparse
        })(),
      }}
    >
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Functions and Methods

Display JavaScript functions, async functions, and generators in your JSON tree:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

const data = [
  function sum(a: number, b: number) {
    return a + b
  },
  async (promises: Promise<any>[]) => await Promise.all(promises),
  function* generator(a: number) {
    while (a > 0) {
      yield a - 1
    }
  },
]

export const Functions = () => {
  return (
    <JsonTreeView.Root defaultExpandedDepth={1} className={styles.Root} data={data}>
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Regular Expressions

Regular expressions are displayed with their pattern and flags:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

const data = {
  regex: /^[a-z0-9]+/g,
  case_insensitive: /^(?:[a-z0-9]+)foo.*?/i,
}

export const Regex = () => {
  return (
    <JsonTreeView.Root defaultExpandedDepth={1} className={styles.Root} data={data}>
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Error Objects

Error objects and their stack traces can be visualized:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

const data = new Error('Error')

export const Errors = () => {
  return (
    <JsonTreeView.Root className={styles.Root} data={data} defaultExpandedDepth={1}>
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Map and Set Objects

Native JavaScript Map and Set objects are supported:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

const data = new Map<string, any>([
  ['name', 'ark-ui-json-tree'],
  ['license', 'MIT'],
  ['elements', new Set(['ark-ui', 123, false, true, null, undefined, 456n])],
  [
    'nested',
    new Map<string, any>([
      [
        'taglines',
        new Set([
          { name: 'ark-ui', feature: 'headless components' },
          { name: 'ark-ui', feature: 'framework agnostic' },
          { name: 'ark-ui', feature: 'accessible by default' },
        ]),
      ],
    ]),
  ],
])

export const MapAndSet = () => {
  return (
    <JsonTreeView.Root defaultExpandedDepth={1} className={styles.Root} data={data}>
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Controlling Expand Level

Use the `defaultExpandedDepth` prop to control how many levels are expanded by default:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

export const ExpandLevel = () => {
  return (
    <JsonTreeView.Root
      className={styles.Root}
      defaultExpandedDepth={2}
      data={{
        name: 'John Doe',
        age: 30,
        email: 'john.doe@example.com',
        tags: ['tag1', 'tag2', 'tag3'],
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.Root>
  )
}
```

### Custom Value Rendering

You can customize how specific values are rendered using the `renderValue` prop. This example shows how to make email
addresses clickable:

```tsx
import { JsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

export const RenderValue = () => {
  return (
    <JsonTreeView.Root
      className={styles.Root}
      defaultExpandedDepth={2}
      data={{
        name: 'John Doe',
        age: 30,
        number: Number.NaN,
        email: 'john.doe@example.com',
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree
        className={styles.Tree}
        arrow={<ChevronRightIcon />}
        renderValue={(node) => {
          if (node.type === 'text' && typeof node.value === 'string' && isEmail(node.value)) {
            return (
              <a href={`mailto:${node.value}`} target="_blank" rel="noreferrer">
                {node.value}
              </a>
            )
          }
        }}
      />
    </JsonTreeView.Root>
  )
}

const isEmail = (value: string) => {
  const strippedValue = value.replace(/^"(.*)"$/, '$1')
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(strippedValue)
}
```

### Configuration Options

The JSON tree view supports several configuration options to customize the display:

```tsx
<JsonTreeView.Root
  data={data}
  defaultExpandedDepth={2}
  quotesOnKeys={true}
  showNonenumerable={true}
  maxPreviewItems={5}
  collapseStringsAfterLength={50}
  groupArraysAfterLength={100}
>
  <JsonTreeView.Tree arrow={<ChevronRightIcon />} />
</JsonTreeView.Root>
```

**Configuration Options:**

- **`quotesOnKeys`**: Whether to show quotes around object keys
- **`showNonenumerable`**: Whether to show non-enumerable properties
- **`maxPreviewItems`**: Maximum number of items to show in object/array previews
- **`collapseStringsAfterLength`**: Collapse strings longer than this length
- **`groupArraysAfterLength`**: Group array items when array is longer than this length

### Using the Root Provider

The `RootProvider` component provides a context for the JSON tree view. It accepts the value of the `useJsonTreeView`
hook. You can leverage it to access the component state and methods from outside the JSON tree view.

```tsx
import { JsonTreeView, useJsonTreeView } from '@ark-ui/react/json-tree-view'
import { ChevronRightIcon } from 'lucide-react'
import styles from 'styles/json-tree-view.module.css'

export const RootProvider = () => {
  const jsonTreeView = useJsonTreeView({
    defaultExpandedDepth: 1,
    data: {
      name: 'John Doe',
      age: 30,
      email: 'john.doe@example.com',
      tags: ['tag1', 'tag2', 'tag3'],
      address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345',
      },
    },
  })

  return (
    <JsonTreeView.RootProvider className={styles.Root} value={jsonTreeView}>
      <JsonTreeView.Tree className={styles.Tree} arrow={<ChevronRightIcon />} />
    </JsonTreeView.RootProvider>
  )
}
```

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

### JsonTreeViewRoot

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`canRename`**
Type: `(node: JsonNode<any>, indexPath: IndexPath) => boolean`
Required: false
Default Value: `undefined`
Description: Function to determine if a node can be renamed

**`checkedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled checked node value

**`collapseStringsAfterLength`**
Type: `number`
Required: false
Default Value: `undefined`
Description: undefined

**`data`**
Type: `{}`
Required: false
Default Value: `undefined`
Description: The data to display in the tree.

**`defaultCheckedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The initial checked node value when rendered.
Use when you don't need to control the checked node value.

**`defaultExpandedDepth`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The default expand level.

**`defaultExpandedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value.

**`defaultFocusedValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The initial focused node value when rendered.
Use when you don't need to control the focused node value.

**`defaultSelectedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The initial selected node value when rendered.
Use when you don't need to control the selected node value.

**`expandedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled expanded node ids

**`expandOnClick`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether clicking on a branch should open it or not

**`focusedValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The value of the focused node

**`groupArraysAfterLength`**
Type: `number`
Required: false
Default Value: `undefined`
Description: undefined

**`hideMode`**
Type: `HideMode`
Required: false
Default Value: `'display-none'`
Description: How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 `<Activity mode="hidden">`. Effects pause. Requires React 19+.

**`ids`**
Type: `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>`
Required: false
Default Value: `undefined`
Description: The ids of the tree elements. Useful for composition.

**`lazyMount`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to enable lazy mounting

**`loadChildren`**
Type: `(details: LoadChildrenDetails<JsonNode<any>>) => Promise<JsonNode<any>[]>`
Required: false
Default Value: `undefined`
Description: Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding.

**`maxPreviewItems`**
Type: `number`
Required: false
Default Value: `undefined`
Description: undefined

**`onBeforeRename`**
Type: `(details: RenameCompleteDetails) => boolean`
Required: false
Default Value: `undefined`
Description: Called before a rename is completed. Return false to prevent the rename.

**`onCheckedChange`**
Type: `(details: CheckedChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Called when the checked value changes

**`onExpandedChange`**
Type: `(details: ExpandedChangeDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when the tree is opened or closed

**`onFocusChange`**
Type: `(details: FocusChangeDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when the focused node changes

**`onLoadChildrenComplete`**
Type: `(details: LoadChildrenCompleteDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when a node finishes loading children

**`onLoadChildrenError`**
Type: `(details: LoadChildrenErrorDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when loading children fails for one or more nodes

**`onRenameComplete`**
Type: `(details: RenameCompleteDetails) => void`
Required: false
Default Value: `undefined`
Description: Called when a node label rename is completed

**`onRenameStart`**
Type: `(details: RenameStartDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when a node starts being renamed

**`onSelectionChange`**
Type: `(details: SelectionChangeDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Called when the selection changes

**`quotesOnKeys`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to show quotes on the keys.

**`scrollToIndexFn`**
Type: `(details: ScrollToIndexDetails<JsonNode<any>>) => void`
Required: false
Default Value: `undefined`
Description: Function to scroll to a specific index.
Useful for virtualized tree views.

**`selectedValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled selected node value

**`selectionMode`**
Type: `'single' | 'multiple'`
Required: false
Default Value: `"single"`
Description: Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected

**`showNonenumerable`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: undefined

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`typeahead`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether the tree supports typeahead search

**`unmountOnExit`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to unmount on exit.

### JsonTreeViewRootProvider

#### Props

**`value`**
Type: `UseJsonTreeViewReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`hideMode`**
Type: `HideMode`
Required: false
Default Value: `'display-none'`
Description: How to hide content when mounted but not present.
- `'display-none'`: HTML `hidden` attribute. Effects stay alive.
- `'activity'`: React 19 `<Activity mode="hidden">`. Effects pause. Requires React 19+.

**`lazyMount`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to enable lazy mounting

**`unmountOnExit`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to unmount on exit.

### JsonTreeViewTree

#### Props

**`arrow`**
Type: `ReactElement<unknown, string | JSXElementConstructor<any>>`
Required: false
Default Value: `undefined`
Description: The icon to use for the arrow.

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`indentGuide`**
Type: `boolean | ReactElement<unknown, string | JSXElementConstructor<any>>`
Required: false
Default Value: `undefined`
Description: The indent guide to use for the tree.

**`renderValue`**
Type: `(node: JsonNodeHastElement) => ReactNode`
Required: false
Default Value: `undefined`
Description: The function to render the value of the node.

## Accessibility

The JSON tree view is built on top of the Tree View component and complies with the
[Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).

### Keyboard Support

**`Tab`**
Description: Moves focus to the tree view, placing the first tree view item in focus.

**`Enter + Space`**
Description: Selects the item or branch node

**`ArrowDown`**
Description: Moves focus to the next node

**`ArrowUp`**
Description: Moves focus to the previous node

**`ArrowRight`**
Description: When focus is on a closed branch node, opens the branch.<br> When focus is on an open branch node, moves focus to the first item node.

**`ArrowLeft`**
Description: When focus is on an open branch node, closes the node.<br> When focus is on an item or branch node, moves focus to its parent branch node.

**`Home`**
Description: Moves focus to first node without opening or closing a node.

**`End`**
Description: Moves focus to the last node that can be focused without expanding any nodes that are closed.

**`a-z + A-Z`**
Description: Focus moves to the next node with a name that starts with the typed character. The search logic ignores nodes that are descendants of closed branch.

**`*`**
Description: Expands all sibling nodes that are at the same depth as the focused node.

**`Shift + ArrowDown`**
Description: Moves focus to and toggles the selection state of the next node.

**`Shift + ArrowUp`**
Description: Moves focus to and toggles the selection state of the previous node.

**`Ctrl + A`**
Description: Selects all nodes in the tree. If all nodes are selected, unselects all nodes.