TreeView

A composable, accessible tree view component with expand/collapse, single & multi-select, keyboard navigation, and indent guide lines.

Preview

src

app
- page.tsx
- layout.tsx
- globals.css
components
- ui
  - button.tsx
  - card.tsx
lib

package.json

tsconfig.json

README.md

Installation

Usage

tsximport {
  TreeView,
  TreeItem,
  TreeItemLabel,
  TreeItemActions,
} from "@/components/ui/tree-view"
import { Folder, FileCode } from "lucide-react"

export function MyTree() {
  return (
    <TreeView defaultExpanded={["src"]} selectionMode="single">
      <TreeItem value="src">
        <TreeItemLabel>
          <Folder className="size-4 text-sky-500" />
          src
        </TreeItemLabel>

        <TreeItem value="index.ts">
          <TreeItemLabel>
            <FileCode className="size-4 text-blue-500" />
            index.ts
          </TreeItemLabel>
        </TreeItem>
      </TreeItem>
    </TreeView>
  )
}

Controlled Mode

Pass expanded and selected props for full control over state.

tsxconst [expanded, setExpanded] = useState(["src"])
const [selected, setSelected] = useState<string[]>([])

<TreeView
  expanded={expanded}
  onExpandedChange={setExpanded}
  selected={selected}
  onSelectedChange={setSelected}
  selectionMode="multiple"
>
  {/* ... */}
</TreeView>

Item Actions

Use TreeItemActions to add hover-visible action buttons.

tsx<TreeItem value="file.ts">
  <TreeItemLabel>
    <FileCode className="size-4" />
    file.ts
  </TreeItemLabel>
  <TreeItemActions>
    <Button variant="ghost" size="icon" className="size-6">
      <Pencil className="size-3" />
    </Button>
    <Button variant="ghost" size="icon" className="size-6">
      <Trash2 className="size-3" />
    </Button>
  </TreeItemActions>
</TreeItem>

API Reference

TreeView

Prop	Type	Default	Description
expanded	string[]	—	Controlled expanded item values.
defaultExpanded	string[]	[]	Items expanded on initial render (uncontrolled).
onExpandedChange	(expanded: string[]) => void	—	Called when expanded state changes.
selected	string[]	—	Controlled selected item values.
defaultSelected	string[]	[]	Items selected on initial render (uncontrolled).
onSelectedChange	(selected: string[]) => void	—	Called when selection changes.
selectionMode	"single" \| "multiple" \| "none"	"single"	How items can be selected.
indicator	boolean	true	Show indent guide lines.
size	"sm" \| "md" \| "lg"	"md"	Text size variant.

TreeItem

Prop	Type	Default	Description
value	string	—	Unique identifier for this item (required).

TreeItemLabel

Prop	Type	Default	Description
children	ReactNode	—	Label content (icons, text, etc.).

TreeItemActions

Prop	Type	Default	Description
children	ReactNode	—	Action buttons shown on hover/focus.

Keyboard Navigation

Key	Action
`Arrow Down`	Move focus to next visible item
`Arrow Up`	Move focus to previous visible item
`Arrow Right`	Expand collapsed node
`Arrow Left`	Collapse expanded node
`Enter`	Select item and toggle expand
`Space`	Select item
`Home`	Move focus to first item
`End`	Move focus to last visible item