Tree

A fully accessible tree view component for displaying hierarchical data structures like file explorers, nested menus, and org charts.

Preview

Installation

npm install @matrix-ui/components

Usage

import { Tree } from '@matrix-ui/components'
import type { TreeNode } from '@matrix-ui/components'

const data: TreeNode[] = [
  {
    id: 'folder-1',
    name: 'Folder',
    children: [
      { id: 'file-1', name: 'File.txt' },
    ],
  },
]

<Tree data={data} />

Examples

Custom Rendering with Icons

Use the renderItem prop to customize how each item is displayed.

Controlled Selection

Control selection state externally with selectedIds and onSelectionChange.

Multiple Selection

Enable multiple selection with selectionMode="multiple". Use Space to toggle selection.

With ScrollArea

Combine with ScrollArea for long lists with custom scrollbars.

Disabled Items

Items can be disabled by setting disabled: true on the node.

Keyboard Navigation

Key	Action
`Arrow Down`	Move focus to next visible node
`Arrow Up`	Move focus to previous visible node
`Arrow Right`	Expand node if collapsed, or move to first child
`Arrow Left`	Collapse node if expanded, or move to parent
`Home`	Move focus to first node
`End`	Move focus to last visible node
`Enter`	Activate item (triggers onItemActivate)
`Space`	Toggle selection
`Type characters`	Type-ahead search to focus matching node

Accessibility

The Tree component follows the WAI-ARIA Tree Pattern and includes:

role="tree" on the container
role="treeitem" on each item
role="group" on nested containers
aria-expanded for expandable items
aria-selected for selectable items
aria-level, aria-setsize, and aria-posinset for position
aria-disabled for disabled items
aria-multiselectable when in multiple selection mode
Roving tabindex for single tab stop navigation

API Reference

Prop	Type	Default
`data`	`TreeNode[]`	Required
`selectionMode`	`'none' \| 'single' \| 'multiple'`	`'single'`
`selectedIds`	`Set<string>`	-
`defaultSelectedIds`	`Set<string>`	`new Set()`
`onSelectionChange`	`(ids: Set<string>) => void`	-
`expandedIds`	`Set<string>`	-
`defaultExpandedIds`	`Set<string>`	`new Set()`
`onExpandedChange`	`(ids: Set<string>) => void`	-
`onItemActivate`	`(id: string, node: TreeNode) => void`	-
`renderItem`	`(node: TreeNode, state: TreeItemState) => ReactNode`	-
`typeAhead`	`boolean`	`true`
`itemClassName`	`string`	-
`aria-label`	`string`	`'Tree'`