Tree View

Installation#

pnpmbunnpmyarn
pnpm dlx shadcn@latest add @shark/tree-view

Anatomy#

TreeView
├── TreeViewLabel
└── TreeViewTree
    └── TreeViewNode
        ├── TreeViewBranch
        │   ├── TreeViewBranchItem
        │   │   └── TreeViewBranchIndicator
        │   └── TreeViewBranchContent
        │       └── TreeViewNode …
        └── TreeViewContent
            └── TreeViewItem
                └── TreeViewCheckbox

Usage#

import {
  TreeView,
  TreeViewLabel,
  TreeViewTree,
  TreeViewNode,
  TreeViewBranch,
  TreeViewBranchItem,
  TreeViewBranchContent,
  TreeViewContent,
  TreeViewItem,
  createTreeCollection,
} from "@/components/ui/tree-view";

const collection = createTreeCollection({
  rootNode: { id: "ROOT", name: "", children: [...] },
});
 
const Example = () => (
  <TreeView collection={collection}>
    <TreeViewTree>
      {collection.rootNode.children?.map((node, index) => (
        <TreeNode indexPath={[index]} key={node.id} node={node} />
      ))}
    </TreeViewTree>
  </TreeView>
)
 
const TreeNode = (props: React.ComponentProps<typeof TreeViewNode>) => {
  const { node, indexPath } = props;
 
  return (
    <TreeViewNode indexPath={indexPath} key={node.id} node={node}>
      {node.children ? (
        <TreeViewBranch>
          <TreeViewBranchItem>{node.name}</TreeViewBranchItem>
          <TreeViewBranchContent>
            {node.children.map((child, index) => (
              <TreeNode indexPath={[...indexPath, index]} key={child.id} node={child} />
            ))}
          </TreeViewBranchContent>
        </TreeViewBranch>
      ) : (
        <TreeViewContent>
          <TreeViewItem>{node.name}</TreeViewItem>
        </TreeViewContent>
      )}
    </TreeViewNode>
  );
};

Controlled#

Use selectedValue and onSelectionChange to control the selected node and react to selection changes.

Examples#

Multiple selection#

Use selectionMode="multiple" to allow selecting multiple nodes.

Hold Shift and click to select a range, or use Ctrl/Cmd+click to toggle individual nodes.

With Context Menu#

Right-click on tree items to show a context menu.

Renaming nodes#

Use the canRename prop and onRenameComplete callback to enable inline renaming of nodes. Press F2 to activate rename mode on the focused node.

With checkboxes#

Use the checkedValue and onCheckedChange props to control the checked nodes.

Links#

Tree items can be rendered as links. Use asChild on TreeViewContent and wrap an <a> element with TreeViewItem inside.

Mini Editor#

Use the tree view to create a file editor.

Custom icons#

There are three ways to customize icons:

1. Folder — icon and expandedIcon props on TreeViewBranchItem, or per-node via TreeNodeType
2. Single item — icon prop on TreeViewItem
3. By extension — fileIcons prop on TreeView with createFileIcons

Folder icons#

Use the icon and expandedIcon props on TreeViewBranchItem to customize folder icons. Pass null to hide the icon.

Single item icon#

Pass the icon prop to TreeViewItem to override the icon for a specific leaf node.

With file extensions#

Use the fileIcons prop on TreeView with createFileIcons to map file extensions to icon components. Icons are resolved from each node's id; unmatched extensions fall back to FileIcon.

API Reference#

TreeView#

Root component. Provides tree context and manages expand/selection state.

TreeViewLabel#

Accessible label for the tree.

TreeViewTree#

Wraps the root-level tree nodes.

TreeViewNode#

Provides tree node context. Must wrap each branch or item.

TreeViewBranch#

Expandable branch with children. Toggles open/closed.

TreeViewBranchItem#

Clickable area to expand or collapse a branch.

TreeViewBranchContent#

Holds the branch children. Shown when expanded.

TreeViewContent#

Wrapper for leaf (non-expandable) items.

TreeViewItem#

Leaf node (non-expandable). The icon prop is fallback when no fileIcons match.

TreeViewCheckbox#

Checkbox for selecting a node in multi-select mode.

createTreeCollection#

Creates a tree collection from node data. Use with collection prop on TreeView.

Options

TreeNodeType — Shape of each node (extend with generic T for custom props):

const collection = createTreeCollection({
  rootNode: { id: "ROOT", name: "", children: [...] },
});
 
// With custom node props
type LinkNode = TreeNodeType & { href?: string };
const links = createTreeCollection<LinkNode>({
  rootNode: {
    id: "docs",
    name: "Docs",
    children: [{ id: "intro", name: "Intro", href: "/intro" }],
  },
});

createFileIcons#

Creates a type-safe mapping of file extensions to icon components. Use with fileIcons prop on TreeView.

Keys use dotted extensions.

const fileIcons = createFileIcons({
  ".tsx": FileCode,
  ".json": FileJson,
  ".md": FileText,
});

For a complete list of props, see the Ark UI documentation.