Tree

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tree

Usage#

import { Tree, TreeItem } from "@/components/ui/tree"

export function Example() {
  return (
    <Tree defaultExpandedValues={["src"]}>
      <TreeItem value="src" label="src">
        <TreeItem value="index.ts" label="index.ts" />
      </TreeItem>
      <TreeItem value="package.json" label="package.json" />
    </Tree>
  )
}

A TreeItem with children is a branch (it renders a caret and a collapsible panel); without children it's a leaf. The value is the node's stable identity for selection and expansion. Pass label and icon so every row stays visually consistent, and nest items as children for depth.

Selection#

Tree holds a single selection. Control it with value / onValueChange, or let it manage its own with defaultValue. Mark any node disabled to take it out of selection, expansion, and the keyboard order.

Trailing actions & guides#

The tree isn't only for files. Drop a count, a badge, or a menu in the actions slot, and turn off the indent rails with guides={false} when the icons alone carry the hierarchy.

Drag to reorder#

Pass onMove and every row becomes draggable. Drop near the top or bottom of a row to place a node before or after it, or onto the middle of a folder to drop it inside. The tree doesn't own your data, so it reports the move and you apply it; dropping a node into its own subtree is blocked, and Alt + ↑ / ↓ reorders siblings from the keyboard.

Keyboard#

Focus the tree and navigate without the mouse: ↑ / ↓ move between visible rows, → expands a collapsed branch then steps into it, ← collapses an open branch then steps out to its parent, Home / End jump to the first and last rows, and Enter / Space select (and toggle a branch).

API reference#

FAQ#