Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsPlaygroundGuidesBlog
Sponsor

TreeView

Used to display hierarchical data structures in an expandable tree format

SourceStorybookRecipeArk

Tree

panda.config.ts
package.json
renovate.json
README.md

Usage

import { TreeView } from "@chakra-ui/react"
<TreeView.Root>
  <TreeView.Label />
  <TreeView.Tree>
    <TreeView.Branch>
      <TreeView.BranchControl>
        <TreeView.BranchIndicator />
        <TreeView.BranchText />
      </TreeView.BranchControl>
      <TreeView.BranchContent>
        <TreeView.BranchIndentGuide />
        <TreeView.Item />
      </TreeView.BranchContent>
    </TreeView.Branch>
    <TreeView.Item />
  </TreeView.Tree>
</TreeView.Root>

Shortcuts

TreeView.Node

This component is a helper to manage the recursive rendering of the branch and leaf nodes.

<TreeView.Node
  showIndentGuide
  render={({ node, nodeState }) =>
    nodeState.isBranch ? (
      <TreeView.BranchControl>
        <TreeView.BranchText>{node.name}</TreeView.BranchText>
      </TreeView.BranchControl>
    ) : (
      <TreeView.Item>
        <TreeView.ItemText>{node.name}</TreeView.ItemText>
      </TreeView.Item>
    )
  }
/>

is equivalent to:

const TreeNode = (props: TreeView.NodeProviderProps<Node>) => {
  const { node, indexPath } = props
  return (
    <TreeView.NodeProvider key={node.id} node={node} indexPath={indexPath}>
      {node.children ? (
        <TreeView.Branch>
          <TreeView.BranchControl>
            <TreeView.BranchText>{node.name}</TreeView.BranchText>
          </TreeView.BranchControl>
          <TreeView.BranchContent>
            <TreeView.BranchIndentGuide />
            {node.children.map((child, index) => (
              <TreeNode
                key={child.id}
                node={child}
                indexPath={[...indexPath, index]}
              />
            ))}
          </TreeView.BranchContent>
        </TreeView.Branch>
      ) : (
        <TreeView.Item>
          <TreeView.ItemText>{node.name}</TreeView.ItemText>
        </TreeView.Item>
      )}
    </TreeView.NodeProvider>
  )
}

Examples

Sizes

Use the size prop to change the size of the tree view.

Tree (size=xs)

panda.config.ts
package.json
renovate.json
README.md

Tree (size=sm)

panda.config.ts
package.json
renovate.json
README.md

Tree (size=md)

panda.config.ts
package.json
renovate.json
README.md

Variants

Use the variant prop to change the variant of the tree view.

Tree (variant=subtle)

panda.config.ts
package.json
renovate.json
README.md

Tree (variant=solid)

panda.config.ts
package.json
renovate.json
README.md

Colors

Use the colorPalette prop to change the color palette of the tree view.

Tree (colorPalette=gray)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=red)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=green)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=blue)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=teal)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=pink)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=purple)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=cyan)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=orange)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=yellow)

panda.config.ts
package.json
renovate.json
README.md

Disabled Node

Adding the disabled prop to a node's property will disable the node and prevent interaction.

Tree

panda.config.ts
package.json
renovate.json
README.md

Controlled Expansion

Use the expandedValue and onExpandedChange props to programmatically control node expansion behavior.

Tree

node_modules
zag-js
panda
panda.config.ts
package.json
renovate.json
README.md

Explicit Expand

Render the TreeView.BranchTrigger to manually control node expansion behavior.

You might need to set role="none" on the TreeView.BranchControl to avoid accessibility issues.

Tree

panda.config.ts
package.json
renovate.json
README.md

Expand Icon

Use the nodeState.expanded prop to swap the rendered icon on the branch when it's expanded or collapsed.

Tree

panda.config.ts
package.json
renovate.json
README.md

Remove Indentation

Set the css variable --tree-indentation to 0px to remove the indentation of the tree view.

Tree

panda.config.ts
package.json
renovate.json
README.md

Async 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.

Tree

panda.config.ts
package.json
renovate.json
README.md

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.

Tree

panda.config.ts
package.json
renovate.json
README.md

Collapse Animation

Use the animateContent prop to animate the tree view content expand/collapse state.

Tree

panda.config.ts
package.json
renovate.json
README.md

Expand/Collapse All

Provide controls to expand or collapse all nodes at once.

Tree

panda.config.ts
package.json
renovate.json
README.md

Store

Use the useTreeView hook to create the tree view store and pass it to the TreeView.RootProvider component. This allows you to have maximum control over the tree view programmatically.

Tree

[]
panda.config.ts
package.json
renovate.json
README.md

Render the tree items as links by leveraging the asChild prop on the TreeView.Item component.

Multi Select

Add the selectionMode="multiple" prop to the TreeView.Root component to enable multi-select functionality.

info

This mode requires a modifier key to be pressed to select multiple items.

  • Hold Ctrl or ⌘ on macOS and click the items.
  • Click an item, then hold Shift while clicking on another item.

Tree

panda.config.ts
package.json
renovate.json
README.md

Checkbox Tree

Add checkboxes to tree nodes for selection functionality.

Tree

panda.config.ts
package.json
renovate.json
README.md

Mutation

Here's an example of how to design add/remove nodes in the tree view.

Tree

panda.config.ts
package.json
renovate.json
README.md

Custom Icon

Here's an example of how to render a custom icon for the tree view based on its data.

Tree

Footer

Props

Root

PropDefaultType
collection *
TreeCollection<T>

The collection of tree nodes

expandOnClick true
boolean

Whether clicking on a branch should open it or not

lazyMount false
boolean

Whether to enable lazy mounting

selectionMode '\'single\''
'multiple' | 'single'

Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected

typeahead true
boolean

Whether the tree supports typeahead search

unmountOnExit false
boolean

Whether to unmount on exit.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
defaultExpandedValue
string[]

The initial expanded items of the tree view. Use this when you do not need to control the state of the tree view.

defaultSelectedValue
string[]

The initial selected items of the tree view. Use this when you do not need to control the state of the tree view.

expandedValue
string[]

The id of the expanded nodes

focusedValue
string

The id of the focused node

ids
Partial<{ root: string tree: string label: string node(value: string): string }>

The ids of the tree elements. Useful for composition.

onExpandedChange
(details: ExpandedChangeDetails) => void

Called when the tree is opened or closed

onFocusChange
(details: FocusChangeDetails) => void

Called when the focused node changes

onSelectionChange
(details: SelectionChangeDetails) => void

Called when the selection changes

selectedValue
string[]

The id of the selected nodes

Node

Previous

Tooltip

Next

ClientOnly