---
id: tree-view
title: Tree View
description: A component that is used to show a tree hierarchy.
---

<ComponentPreview id="TreeView" />

## Anatomy

<Anatomy id="tree-view" />

```tsx
<TreeView.Root>
  <TreeView.Label />
  <TreeView.Tree>
    <TreeView.NodeProvider>
      <TreeView.Branch>
        <TreeView.BranchControl>
          <TreeView.BranchIndicator />
          <TreeView.BranchText />
        </TreeView.BranchControl>
        <TreeView.BranchContent>
          <TreeView.BranchIndentGuide />
          <TreeView.Item>
            <TreeView.ItemText />
          </TreeView.Item>
        </TreeView.BranchContent>
      </TreeView.Branch>
    </TreeView.NodeProvider>
  </TreeView.Tree>
</TreeView.Root>
```

## Examples

<Example id="basic" />

### Controlled Expanded

Pass the `expandedValue` and `onExpandedChange` props to the `TreeView.Root` component to control the expanded state of
the tree view.

<Example id="controlled-expanded" />

### Controlled Selection

Pass the `selectedValue` and `onSelectionChange` props to the `TreeView.Root` component to control the selected state of
the tree view.

<Example id="controlled-selected" />

### Root Provider

An alternative way to control the tree view is to use the `RootProvider` component and the `useTreeView` hook. This way
you can access the state and methods from outside the component.

<Example id="root-provider" />

### Lazy Loading

Lazy loading is a feature that allows the tree view to load children of a node on demand (or async). This helps to
improve the initial load time and memory usage.

To use this, you need to provide the following:

- `loadChildren` — A function that is used to load the children of a node.
- `onLoadChildrenComplete` — A callback that is called when the children of a node are loaded. Used to update the tree
  collection.
- `childrenCount` — A number that indicates the number of children of a branch node.

<Example id="async-loading" />

### Lazy Mount

Lazy mounting is a feature that allows the content of a tree view to be rendered only when it is expanded. This is
useful for performance optimization, especially when tree content is large or complex. To enable lazy mounting, use the
`lazyMount` prop on the `TreeView.Root` component.

In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tree view content when
branches are collapsed, freeing up resources. The next time a branch is expanded, its content will be re-rendered.

<Example id="lazy-mount" />

### Filtering

Filtering is useful when you have a large tree and you want to filter the nodes to only show the ones that match the
search query. Here's an example that composes the `filter` method from the `TreeCollection` and `useFilter` hook to
filter the nodes.

<Example id="filtering" />

### Links

Tree items can be rendered as links to another page or website. This could be useful for documentation sites.

Here's an example that modifies the tree collection to represent an hierarchical link structure. It uses the `asChild`
prop to render the tree items as links, passing the `href` prop to a `<a>` element.

<Example id="links" />

### Virtualized

For large tree views with thousands of nodes, virtualization can significantly improve performance by only rendering
visible nodes.

Key implementation details:

- Use `useTreeView` hook with `TreeView.RootProvider` for programmatic control
- Pass `scrollToIndexFn` to enable keyboard navigation within the virtualized list
- Use `getVisibleNodes()` to get the flattened list of currently visible nodes

<Example id="virtualized" />

### Checkbox Tree

Use the `defaultCheckedValue` prop to enable checkbox selection mode. This allows users to select multiple nodes with
checkboxes, including parent-child selection relationships.

<Example id="checkbox-tree" />

### Expand and Collapse All

Use the `expand()` and `collapse()` methods from the tree view context to programmatically expand or collapse all
branches.

<Example id="expand-collapse-all" />

### Mutation

Use the collection's `remove()` and `replace()` methods to dynamically add and remove nodes from the tree. This is
useful for building file explorer interfaces where users can create and delete files.

<Example id="mutation" />

### Rename Node

Enable inline renaming of nodes using the `canRename` prop and `onRenameComplete` callback. Press <kbd>F2</kbd> to
activate rename mode on the focused node.

<Example id="rename-node" />

## Guides

### Type Safety

The `TreeView.RootComponent` type enables you to create typed wrapper components that maintain full type safety for tree
nodes.

```tsx
import { TreeView as ArkTreeView } from '@ark-ui/react/tree-view'

const TreeView: ArkTreeView.RootComponent = (props) => {
  return <ArkTreeView.Root {...props}>{/* ... */}</ArkTreeView.Root>
}
```

Use the wrapper with full type inference on `onSelectionChange` and other callbacks:

```tsx
const App = () => {
  const collection = createTreeCollection({
    initialItems: [
      { id: '1', label: 'React', children: [] },
      { id: '2', label: 'Vue', children: [] },
    ],
  })
  return (
    <TreeView
      collection={collection}
      onSelectionChange={(e) => {
        // e.items is typed as Array<{ id: string, label: string, children: [] }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </TreeView>
  )
}
```

## API Reference

### Props

<ComponentTypes id="tree-view" />

### Context

<ContextType id="tree-view" />

## Accessibility

Complies with the [Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).

### Keyboard Support

<KeyBindingsTable id="tree-view" />
