Tree

The tree displays nested data as an expandable hierarchy with selection, checkboxes, and keyboard navigation. Use it for file explorers, nav menus, category pickers, or any parent-child structure. It renders each node through a child function, so you control the markup of every row.

Preview

Installation

npx shadcn@latest add @cubby-ui/tree

Usage

import {
  Tree,
  TreeItem,
  TreeItemLabel,
  TreeNode,
} from "@/components/ui/cubby-ui/tree";

<Tree>
  <TreeItem>
    <TreeItemLabel />
  </TreeItem>
</Tree>

Composition

Tree                      (data + render function)
└── TreeItem
    ├── TreeItemIcon
    ├── TreeItemLabel
    └── TreeItemBadge

Tree takes a data array and a child function that returns a TreeItem for each node. Compose the row from TreeItemIcon, TreeItemLabel, and TreeItemBadge.

Examples

Variants

Use variant to set the tree's surface treatment.

With Icons

Set icon on a node and iconOpen for a different icon while it is expanded.

With Lines

Use showLines to draw connecting lines between parent and child nodes.

With Badges

Set badge on a node and render it with TreeItemBadge.

With Checkboxes

Use mode="multiple" to add checkboxes; parent state reflects child selection automatically.

Controlled State

Use expanded/onExpandedChange and selectedNode/onNodeSelect to drive state externally.

Disabled & Loading States

Set disabled or loading on individual nodes, or mode="none" for a read-only tree.

Async Loading

Use onLoadChildren on a node to fetch children on first expand; the tree shows a spinner and caches the result.

Accessibility

The tree is operable from the keyboard: arrow keys move between and expand/collapse nodes, and Enter or Space selects. Selection and expansion state are reflected via aria attributes on each node, and disabled nodes are skipped during navigation.

API Reference

The Tree component is built with Base UI's Collapsible internally for expand/collapse functionality. All Collapsible props are supported on tree nodes. The documentation below only covers custom props specific to our Tree implementation.

For the complete Base UI Collapsible API, see the Base UI Collapsible documentation.

Props

Tree

Hierarchical view for displaying nested data with selection and expansion. Uses Base UI's Collapsible internally.

TreeNode Interface

TypeScript interface defining the shape of each tree node: