Tree
Nested, expandable rows for files and hierarchies, with indent guides, connector lines, cascading checkboxes, typeahead and full keyboard support.
- Data display components
- 4 parts
- 12 examples
@base-ui/react@tabler/icons-reactclass-variance-authority
See it in a real product: Diff Review and Tool Calls
View blockpnpm dlx shadcn@latest add https://hextaui.com/r/tree.jsonAdds the component, the HextaUI theme tokens and any HextaUI components it depends on.
Add the theme tokens to your global CSS, if you haven’t yet.
Install the dependencies.
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cnCopy and paste the following code into your project.
components/ui/tree.tsx components/ui/checkbox.tsx Update the import paths to match your project setup.
An item with a <TreeGroup /> is a branch: it gets a chevron, opens and closes, and answers to the arrow keys. Every item needs a value that is unique within the tree.
variant="lines" draws a guide for each level. The guide of the branch that holds the selected or focused row gets darker, so you can see where you are in deep trees.
variant="connectors" joins each item to its parent with an elbow, like a terminal tree listing. Use meta for versions, sizes or counts.
With checkboxes, checking a branch checks every enabled item inside it, and a partly checked branch shows a dash. Checking a branch also counts as checking children you load later. Clicking a row checks it, and the chevron opens it.
Render rows as links with render. Pass the current page to selectedValues, open its section, and set aria-current on its row.
selectionMode="multiple" works like a file manager: click to select one row, Cmd/Ctrl+click to add or remove one, Shift+click to select a range. On touch screens a tap adds or removes the row.
Keep open branches in your own state with expandedValues and onExpandedValuesChange. This example also builds the tree from data with a recursive function.
Fetch children in onExpandedChange on <TreeItem />. Render a disabled loading row until they arrive, so the branch keeps its chevron.
size="sm" uses shorter rows and tighter indents, for sidebars. Rows grow on touch screens in both sizes.
A disabled item can’t be selected, checked or opened, and the arrow keys skip it. Items inside a disabled branch are disabled too.
Names cut off with an ellipsis and meta stays visible. Pass title to show the full name on hover.
Indents, connectors and chevrons mirror, and the left and right arrow keys swap.
| Key | Action |
|---|---|
| ↓ | Moves focus to the next visible row. |
| ↑ | Moves focus to the previous visible row. |
| → | Opens a closed branch. On an open branch, moves focus to its first child. |
| ← | Closes an open branch. Otherwise moves focus to the parent. |
| Home | Moves focus to the first row. |
| End | Moves focus to the last visible row. |
| Enter | Selects the row and opens or closes it if it is a branch. Follows the link on link rows. |
| Space | Selects the row, adds or removes it in multiple mode, or checks it with checkboxes. |
| Shift + ↑Shift + ↓ | Extends the selection in multiple mode. |
| Cmd/Ctrl + A | Selects every visible row in multiple mode. |
| * | Opens every branch at the focused row’s level. |
| a–z | Moves focus to the next row whose name starts with the typed letters. |
The tree follows the WAI-ARIA tree view pattern. Each row is the treeitem and owns its group through aria-owns, so a row’s name is only its own label and link rows work as real links. Only one row is in the tab order at a time. When a branch closes around the focused row, focus moves to that branch instead of getting lost.
Closed groups stay in the page, so the browser’s find-in-page opens the folders around a match, and checking a branch sees every item inside it. Give the tree an aria-label.
Branches open and close with the Base UI collapsible. <TreeItem /> and <TreeGroup /> accept the props of the parts they wrap.
| Prop | Type | Default |
|---|---|---|
variant | "default" | "lines" | "connectors" | "default" |
size | "default" | "sm" | "default" |
selectionMode | "none" | "single" | "multiple" | "single" |
selectedValues | string[] | – |
defaultSelectedValues | string[] | – |
onSelectedValuesChange | (values: string[]) => void | – |
expandedValues | string[] | – |
defaultExpandedValues | string[] | – |
onExpandedValuesChange | (values: string[]) => void | – |
checkboxesShow cascading checkboxes. Rows are checked instead of selected. | boolean | false |
checkedValuesChecked items. A branch in the list counts as checking its children. | string[] | – |
defaultCheckedValues | string[] | – |
onCheckedValuesChangeCalled with every checked leaf and every fully checked branch. | (values: string[]) => void | – |
disabled | boolean | false |
hiddenUntilFoundLet find-in-page open closed branches around a match. | boolean | true |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribute | Description |
|---|---|
data-slot="tree" | Target the root in CSS. |
data-variant | The current variant. |
data-size | The current size. |
--tree-row-height | Row height. Larger on touch screens. |
--tree-indent | How far each level is indented. |
| Prop | Type | Default |
|---|---|---|
valueRequired. Unique within the tree. | string | – |
disabled | boolean | false |
onExpandedChangeCalled when this item opens or closes. | (expanded: boolean) => void | – |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribute | Description |
|---|---|
data-slot="tree-item" | Target items in CSS. |
data-open | Present when the item is open. |
data-disabled | Present when the item is disabled. |
| Prop | Type | Default |
|---|---|---|
iconShown before the label. | ReactNode | – |
expandedIconCrossfades in for icon while the branch is open. | ReactNode | – |
metaShown at the end of the row, such as a size, count or status. | ReactNode | – |
className | string | – |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribute | Description |
|---|---|
data-slot="tree-item-label" | Target rows in CSS. |
data-value | The item’s value. |
data-expanded | Present when the branch is open. |
data-selected | Present when the row is selected. |
data-checked | Present when the row is checked. |
data-indeterminate | Present when only some children are checked. |
data-disabled | Present when the item is disabled. |
| Prop | Type | Default |
|---|---|---|
classNameApplied to the inner wrapper, so padding never fights the height animation. | string | – |
| Attribute | Description |
|---|---|
data-slot="tree-group" | Target groups in CSS. |
data-open | Present when the group is open. |
data-starting-style | Present while the group animates in. |
data-ending-style | Present while the group animates out. |
--collapsible-panel-height | The group’s measured height, used for the height animation. |
- CheckboxA checkbox whose check draws in, with indeterminate parents, groups and labels that share its hover.
- AvatarUser photos with an initials fallback, status badges and stacked groups that collapse into a count.
- BadgeStatus labels with colored dots, removable tags that slide closed and counts that roll to their new value.
- CardA surface for grouping content, with three variants, edge-to-edge media, concentric radii and whole-card links.
- ChartRecharts charts with themed colors, a tooltip and legend that read labels from one config, and keyboard navigation with a visible focus ring.
- Data tableA table for real data, with sorting, search, row selection, pinned columns, a sticky header and pagination.
Used in Pro blocks
Blocks that build on Tree.
Every block comes with HextaUI Pro, and Prompt Input is free.