Tree View

A component that is used to show a tree hierarchy.

Anatomy

<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

Controlled Expanded

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

Controlled Selection

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

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.

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.

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.

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.

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.

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

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.

Expand and Collapse All

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

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.

Rename Node

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

Guides

Type Safety

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

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:

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

Root

BranchContent

Renders a <div> element.

BranchControl

Renders a <div> element.

BranchIndentGuide

Renders a <div> element.

BranchIndicator

Renders a <div> element.

Branch

Renders a <div> element.

BranchText

Renders a <span> element.

BranchTrigger

Renders a <div> element.

ItemIndicator

Renders a <div> element.

Item

Renders a <div> element.

ItemText

Renders a <span> element.

Label

Renders a <h2> element.

NodeCheckboxIndicator

NodeCheckbox

Renders a <span> element.

NodeProvider

NodeRenameInput

Renders a <input> element.

RootProvider

Tree

Renders a <div> element.

Context

API

Accessibility

Complies with the Tree View WAI-ARIA design pattern.

Keyboard Support