Components
Tree view

Tree View

A component that is used to show a tree hierarchy.

Anatomy

To set up the tree view component 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 TreeView component in your project. Let's take a look at the most basic example:

import { TreeView } from '@ark-ui/react/tree-view'

export const Basic = () => {
  return (
    <TreeView.Root>
      <TreeView.Label>Tree</TreeView.Label>
      <TreeView.Tree>
        <TreeView.Item value="1.0">
          <TreeView.ItemText>1.0</TreeView.ItemText>
        </TreeView.Item>
        <TreeView.Branch value="2.0">
          <TreeView.BranchControl>
            <TreeView.BranchIndicator>↕️</TreeView.BranchIndicator>
            <TreeView.BranchText>2.0</TreeView.BranchText>
          </TreeView.BranchControl>
          <TreeView.BranchContent>
            <TreeView.Item value="2.1">
              <TreeView.ItemText>2.2</TreeView.ItemText>
            </TreeView.Item>
            <TreeView.Item value="2.2">
              <TreeView.ItemText>2.2</TreeView.ItemText>
            </TreeView.Item>
          </TreeView.BranchContent>
        </TreeView.Branch>
      </TreeView.Tree>
    </TreeView.Root>
  )
}

API Reference

Root

PropDefaultType
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

expandOnClicktrue
boolean

Whether clicking on a branch should open it or not

focusedValue
string

The id of the focused node

ids
Partial<{ root: string; tree: string; label: 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

selectionMode'single'
'multiple' | 'single'

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

typeaheadtrue
boolean

Whether the tree supports typeahead search

BranchContent

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]branch-content
[data-branch]
[data-state]"open" | "closed"

BranchControl

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]branch-control
[data-state]"open" | "closed"
[data-disabled]Present when disabled
[data-selected]Present when selected
[data-branch]
[data-depth]The depth of the item

BranchIndicator

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]branch-indicator
[data-state]"open" | "closed"
[data-disabled]Present when disabled
[data-selected]Present when selected
[data-focus]Present when focused

Branch

PropDefaultType
value
string

The id of the item or branch

asChild
boolean

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

For more details, read our Composition guide.
disabled
boolean

Whether the item or branch is disabled

Data AttributeValue
[data-scope]tree-view
[data-part]branch
[data-depth]The depth of the item
[data-branch]
[data-selected]Present when selected
[data-state]"open" | "closed"
[data-disabled]Present when disabled

BranchText

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]branch-text
[data-branch]
[data-disabled]Present when disabled
[data-state]"open" | "closed"

BranchTrigger

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]branch-trigger
[data-disabled]Present when disabled
[data-state]"open" | "closed"

ItemIndicator

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]item-indicator
[data-disabled]Present when disabled
[data-selected]Present when selected
[data-focus]Present when focused

Item

PropDefaultType
value
string

The id of the item or branch

asChild
boolean

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

For more details, read our Composition guide.
disabled
boolean

Whether the item or branch is disabled

Data AttributeValue
[data-scope]tree-view
[data-part]item
[data-item]
[data-focus]Present when focused
[data-selected]Present when selected
[data-disabled]Present when disabled
[data-depth]The depth of the item

ItemText

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tree-view
[data-part]item-text
[data-disabled]Present when disabled
[data-selected]Present when selected
[data-focus]Present when focused

Label

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.

RootProvider

PropDefaultType
value
UseTreeViewReturn

asChild
boolean

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

For more details, read our Composition guide.

Tree

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.

Accessibility

Complies with the Tree View WAI-ARIA design pattern.

Keyboard Support

KeyDescription
Tab
Moves focus to the tree view, placing the first tree view item in focus.
EnterSpace
Selects the item or branch node
ArrowDown
Moves focus to the next node
ArrowUp
Moves focus to the previous node
ArrowRight
When focus is on a closed branch node, opens the branch.
When focus is on an open branch node, moves focus to the first item node.
ArrowLeft
When focus is on an open branch node, closes the node.
When focus is on an item or branch node, moves focus to its parent branch node.
Home
Moves focus to first node without opening or closing a node.
End
Moves focus to the last node that can be focused without expanding any nodes that are closed.
a-zA-Z
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.
*
Expands all sibling nodes that are at the same depth as the focused node.
Shift + ArrowDown
Moves focus to and toggles the selection state of the next node.
Shift + ArrowUp
Moves focus to and toggles the selection state of the previous node.
Ctrl + A
Selects all nodes in the tree. If all nodes are selected, unselects all nodes.