Tree View

A component that is used to show a tree hierarchy.

Item 1
- Item 1.1
- Item 1.2
  - Item 1.2.1
  - Item 1.2.2
Item 2
- Item 2.1
- Item 2.2
Item 3

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>
  )
}

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

export const Basic = () => {
  return (
    <TreeView.Root defaultSelectedValue={['1.0']}>
      <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>
  )
}

<script setup lang="ts">
import { TreeView } from '@ark-ui/vue/tree-view'
</script>

<template>
  <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.BranchTrigger>↕️</TreeView.BranchTrigger>
          <TreeView.BranchText>2.0</TreeView.BranchText>
          <TreeView.BranchIndicator>↕️</TreeView.BranchIndicator>
        </TreeView.BranchControl>
        <TreeView.BranchContent>
          <TreeView.Item value="2.1">
            <TreeView.ItemText>2.1</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>
</template>

Using the Root Provider

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

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

export const RootProvider = () => {
  const treeView = useTreeView()

  return (
    <>
      <button onClick={() => treeView.collapse(['1.0'])}>Collapse 1.0</button>

      <TreeView.RootProvider value={treeView}>
        <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.RootProvider>
    </>
  )
}

import { TreeView, useTreeView } from '@ark-ui/solid/tree-view'

export const RootProvider = () => {
  const treeView = useTreeView({ defaultSelectedValue: ['1.0'] })

  return (
    <>
      <button onClick={() => treeView().collapse(['1.0'])}>Collapse 1.0</button>

      <TreeView.RootProvider value={treeView}>
        <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.RootProvider>
    </>
  )
}

<script setup lang="ts">
import { TreeView, useTreeView } from '@ark-ui/vue/tree-view'

const treeView = useTreeView()
</script>

<template>
  <button @click="treeView.collapse(['1.0'])">Collapse 1.0</button>

  <TreeView.RootProvider :value="treeView">
    <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.BranchTrigger>↕️</TreeView.BranchTrigger>
          <TreeView.BranchText>2.0</TreeView.BranchText>
          <TreeView.BranchIndicator>↕️</TreeView.BranchIndicator>
        </TreeView.BranchControl>
        <TreeView.BranchContent>
          <TreeView.Item value="2.1">
            <TreeView.ItemText>2.1</TreeView.ItemText>
          </TreeView.Item>
          <TreeView.Item value="2.2">
            <TreeView.ItemText>2.2</TreeView.ItemText>
          </TreeView.Item>
        </TreeView.BranchContent>
      </TreeView.Branch>
    </TreeView.Tree>
  </TreeView.RootProvider>
</template>

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

API Reference

Root

Prop	Default	Type
`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
`expandOnClick`	`true`	`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
`typeahead`	`true`	`boolean` Whether the tree supports typeahead search

BranchContent

Prop	Default	Type
`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 Attribute	Value
`[data-scope]`	tree-view
`[data-part]`	branch-content
`[data-branch]`
`[data-state]`	"open" \| "closed"

BranchControl

Prop	Default	Type
`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 Attribute	Value
`[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

Prop	Default	Type
`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 Attribute	Value
`[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

Prop	Default	Type
`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 Attribute	Value
`[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

Prop	Default	Type
`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 Attribute	Value
`[data-scope]`	tree-view
`[data-part]`	branch-text
`[data-branch]`
`[data-disabled]`	Present when disabled
`[data-state]`	"open" \| "closed"

BranchTrigger

Prop	Default	Type
`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 Attribute	Value
`[data-scope]`	tree-view
`[data-part]`	branch-trigger
`[data-disabled]`	Present when disabled
`[data-state]`	"open" \| "closed"

ItemIndicator

Prop	Default	Type
`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 Attribute	Value
`[data-scope]`	tree-view
`[data-part]`	item-indicator
`[data-disabled]`	Present when disabled
`[data-selected]`	Present when selected
`[data-focus]`	Present when focused

Item

Prop	Default	Type
`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 Attribute	Value
`[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

Prop	Default	Type
`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 Attribute	Value
`[data-scope]`	tree-view
`[data-part]`	item-text
`[data-disabled]`	Present when disabled
`[data-selected]`	Present when selected
`[data-focus]`	Present when focused

Label

Prop	Default	Type
`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

Prop	Default	Type
`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

Prop	Default	Type
`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

Key	Description
`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.