Tree view

When to use #

Use it for

Folders, categories and org charts.
Items that have a clear parent and child.

Skip it when

File navigation with keyboard type-ahead; use the file tree.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/tree-view.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { File, Folder } from "lucide-react"
import { useState } from "react"
import { TreeView } from "@/components/ui/tree-view"

export function FolderTree() {
  const [selected, setSelected] = useState<string | null>("brief");
  return (
    <div className="w-full max-w-xs">
      <TreeView
        label="Project folders"
        selected={selected}
        onSelect={setSelected}
        defaultExpanded={["design"]}
        items={[
          { id: "design", label: "Design", icon: <Folder aria-hidden="true" />, meta: "3", children: [{ id: "brief", label: "Brief.pdf", icon: <File aria-hidden="true" /> }, { id: "moodboard", label: "Moodboard.fig", icon: <File aria-hidden="true" /> }] },
          { id: "build", label: "Build", icon: <Folder aria-hidden="true" />, meta: "1", children: [{ id: "spec", label: "Spec.md", icon: <File aria-hidden="true" /> }] },
        ]}
      />
    </div>
  );
}

API reference #

TreeView

component

PropTypeDefault

label *string—

items *readonly TreeItem[]—

selectedstring | null—

defaultSelectedstring | nullnull

onSelect((id: string) => void)—

expandedreadonly string[]—

defaultExpandedreadonly string[][]

onExpandedChange((ids: string[]) => void)—

classNamestring—

It exposes treeitem, group and tree semantics, with aria-level, aria-setsize, aria-posinset, aria-expanded, aria-selected and aria-disabled kept in step with state.

KeyBehaviour

↓Moves to the next item or value.

↑Moves to the previous item or value.

HomeJumps to the first item or the minimum.

EndJumps to the last item or the maximum.

→Moves to the next item or value.

←Moves to the previous item or value.

EnterActivates the focused control.

SpaceActivates the focused control.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.