Navigation & Disclosure
Tree
Accessible hierarchical tree view with composable items, controlled expansion/selection, keyboard navigation, and height-based expand animation. Organize content into understandable destinations and reveal detail when it becomes relevant. Keep the active location or expanded state easy to recognize. Import it from @/components/kamod-ui/tree.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import TreeProvider, Tree, and TreeItem from @kamod-ch/ui/tree.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
import { Tree, TreeItem, TreeProvider } from "@kamod-ch/ui";Usage
Wrap Tree in TreeProvider. Nest TreeItem children for branches. Provide aria-label or aria-labelledby on Tree.
import { Tree } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
<TreeProvider defaultExpandedIds={["documents"]}>
<Tree aria-label="Files">
<TreeItem nodeId="documents" label="Documents">
<TreeItem nodeId="readme" label="README.md" />
</TreeItem>
</Tree>
</TreeProvider>Component Examples & Variants
Explore Tree in Different Contexts, from the starting pattern to the compositions below. Begin with Basic File Tree, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Basic File Tree
Use Stable Identities for the Hierarchy. Start with a small nested tree whose Documents branch is open initially. Stable node identifiers connect each item to its expansion and selection state, while the nesting describes which files belong to each folder.
Distinguish opening a branch from activating a leaf, and keep names useful without relying on file icons alone.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDefault Expanded
Choose an Initial View that Provides Orientation. Supply defaultExpandedIds with the branch identifiers that should be visible on the first render. This establishes the initial reading context without requiring the parent to manage every later expansion change.
Treat defaultExpandedIds as an initial state choice, use IDs present in the data and compare Controlled Expansion when another control must change visibility later.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthControlled Expansion
Coordinate Open Branches from One State Owner. Pass expandedIds from Preact state and handle onExpandedChange when other controls need to open or close branches. Keeping the expanded collection in one place lets the tree and those external actions stay synchronized.
Update the same collection through onExpandedChange, discard obsolete IDs when the data changes and avoid resetting the user's open branches on every unrelated render.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSingle Selection
Keep the Selected Node Distinct from Focus. Set selectionMode="single" when the tree identifies one current item, optionally starting with defaultSelectedIds. Selection communicates the chosen node, while expansion remains a separate question of which descendants are visible.
Use stable IDs and decide what selecting a branch means in the surrounding workflow.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthMultiple Selection
Make the Selected Set and Its Scope Clear. Set selectionMode="multiple" when a task operates on several nodes at once. Ctrl/Cmd-click and Ctrl/Cmd-Space toggle membership in the selection, giving pointer and keyboard users access to the same collection of choices.
Keep the collection synchronized with the current data, provide a readable selection summary and test modifier-key behavior alongside ordinary single-item activation.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthWithout Icons and Lines
Let Indentation and Labels Carry the Structure. Turn off connector lines and icon slots when a compact hierarchy can be understood from labels and indentation alone. The quieter presentation should still preserve clear expansion controls and a recognizable selected item.
Open a deeply nested branch and compare it with its siblings to confirm that the remaining indentation is sufficient. Keep a useful label visible after truncation, particularly when several folders share the same beginning.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthVariants and Sizes
Apply Density Consistently Across the Hierarchy. Set variant and size on TreeProvider to coordinate the treatment across every node. This gives the hierarchy one consistent density while allowing individual labels and state indicators to communicate their local meaning.
Check long labels, focus rings and action slots at each size, and avoid shrinking a dense tree until its expansion controls become difficult to activate.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDisabled Items
Explain Unavailable Nodes without Breaking the Hierarchy. Mark unavailable nodes as disabled so they cannot be selected and are skipped during keyboard navigation. Keep their labels understandable within the hierarchy, especially when the disabled node explains a missing or restricted resource.
Keep the current selection valid when permissions change and verify keyboard travel past disabled entries.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDeep Structure and Long Labels
Keep Long Paths Navigable without Widening the Page. Nest nodes to describe deeper levels and let the tree derive their level information. Labels use start alignment and truncation, so test long folder names alongside the indentation rather than assuming every depth has equal space.
Provide a way to inspect truncated names where necessary, and consider whether several levels belong in a separate detail view rather than one indefinitely indented list.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAdvanced Compound API
Customize the Row While Preserving the Tree Contract. Compose TreeNode, TreeNodeTrigger, TreeExpander, TreeIcon, TreeLabel and TreeNodeContent when a row needs a custom layout. This can coexist with TreeItem, allowing simpler branches to retain the convenient composition.
Keep node identities and semantic relationships intact, and test keyboard behavior after adding actions or moving slots; visual freedom should not create competing nested triggers.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthCustom Icons
Choose Symbols that Explain Node Kinds. Pass an exported Kamod icon or a custom Preact SVG to represent each node. TreeIcon can also render from TreeIconState, letting the symbol reflect the item's state without introducing a second selection model.
Use the render state when appearance depends on expansion or selection, and keep the icon implementation lightweight rather than introducing another component framework.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthState-Specific Icons
Use State Changes to Reinforce Existing Cues. Use state-specific icons when disabled, selected or expanded nodes need a distinct visual cue. The priority is disabledIcon, selectedIcon, expandedIcon, the node's own icon, then the provider default, so overlapping states resolve predictably.
Review the documented priority when combining overrides and keep disabled nodes understandable even when their normal symbol is replaced.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProvider Default Icons
Set a Coherent Baseline before Overriding Individual Nodes. Set branch, branchExpanded and leaf icons on TreeProvider for consistent defaults across the hierarchy. Individual node icons can override those defaults when a particular file or folder needs a more specific representation.
Reserve per-node icons for meaningful differences, and check the expanded branch symbol alongside the collapsed one so their relationship remains recognizable.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthTreeNodeActions
Keep Row Actions Separate from Navigation. Place row-specific badges or buttons inside TreeNodeActions to separate them from the node's selection target. Its event isolation prevents an action from also expanding or selecting the row simply because it is positioned inside it.
Give each action a useful accessible name, preserve the event isolation supplied by the slot and test keyboard access as well as clicking on the icon.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthCustom Preact SVG Icon
Keep Custom Graphics Compatible with the Existing Renderer. Use a Preact SVG component as a tree icon when your project has its own visual language. The icon slot accepts that component without requiring the tree primitive to depend on the same icon package as the application.
Forward the sizing and styling attributes it needs, and treat the graphic as decorative when the node label already supplies its meaning.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthKeyboard
Verify the Hierarchy without a Pointer. Use arrow keys to move through visible nodes, Home/End to reach the boundaries and Enter/Space to activate the focused node. In multiple-selection mode, Ctrl/Cmd+A selects visible items, so collapsed descendants are a distinct case to test.
Exercise an expanded branch, a collapsed branch and a disabled node before integrating custom row actions. Verify that focus remains on an understandable item after changes to the tree and that an action button does not also toggle its parent node.
Accessibility
Tree uses tree/treeitem/group roles, hierarchical levels, expanded state and optional selection state. It requires an accessible name and warns during development when one is missing. Selection mode and expansion are separate concerns.
Props and Data
Configure Tree using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props overview.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Tree
TreeProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
TreeExpander
TreeExpanderProps
| Prop / type | Description |
|---|---|
class | Configure
|
TreeIcon
TreeIconProps
| Prop / type | Description |
|---|---|
class | Configure
|
disabledIcon | Configure
|
expandedIcon | Configure
|
icon | Configure
|
selectedIcon | Configure
|
TreeItem
TreeItemProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
data | Configure
|
disabled | Configure
|
disabledIcon | Configure
|
endContent | Configure
|
expandedIcon | Configure
|
icon | Configure
|
label | Configure
|
nodeId | Configure
|
selectedIcon | Configure
|
TreeLabel
TreeLabelProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
TreeLines
TreeLinesProps
| Prop / type | Description |
|---|---|
class | Configure
|
indent | Configure
|
isLast | Configure
|
level | Configure
|
parentPath | Configure
|
TreeNode
TreeNodeProps
| Prop / type | Description |
|---|---|
children | Configure
|
data | Configure
|
disabled | Configure
|
disabledIcon | Configure
|
expandedIcon | Configure
|
icon | Configure
|
nodeId | Configure
|
selectedIcon | Configure
|
TreeNodeActions
TreeNodeActionsProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
onClick | Configure
|
onKeyDown | Configure
|
TreeNodeContent
TreeNodeContentProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
TreeNodeTrigger
TreeNodeTriggerProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
onClick | Configure
|
onFocus | Configure
|
TreeProvider
TreeProviderProps
| Prop / type | Description |
|---|---|
animateExpand | Configure
|
children | Configure
|
class | Configure
|
defaultExpandedIds | Configure
|
defaultSelectedIds | Configure
|
expandedIds | Configure
|
icons | Configure
|
indent | Configure
|
onExpandedChange | Configure
|
onSelectionChange | Configure
|
selectedIds | Configure
|
selectionMode | Configure
|
showIcons | Configure
|
showLines | Configure
|
size | Configure
|
variant | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
Tree Props
2 declared fieldsTreePropsTree.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeProps before adapting it.TreeItem Props
11 declared fieldsTreeItemPropsTreeItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeItemProps before adapting it.nodeId, labelTreeLines Props
5 declared fieldsTreeLinesPropsTreeLines.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeLinesProps before adapting it.level, parentPath, isLast, indentTreeNodeContextValue
12 declared fieldsTreeNodeContextValueTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeContextValue before adapting it.nodeId, disabled, hasChildren, level, parentPath, isLast, itemRefTreeNode Props
8 declared fieldsTreeNodePropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeProps before adapting it.nodeIdTreeNodeTrigger Props
2 declared fieldsTreeNodeTriggerPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeTriggerProps before adapting it.TreeExpander Props
1 declared fieldTreeExpanderPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeExpanderProps before adapting it.TreeIcon Props
5 declared fieldsTreeIconPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeIconProps before adapting it.TreeLabel Props
2 declared fieldsTreeLabelPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeLabelProps before adapting it.TreeNodeActions Props
2 declared fieldsTreeNodeActionsPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeActionsProps before adapting it.TreeNodeContent Props
2 declared fieldsTreeNodeContentPropsTreeNode.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeContentProps before adapting it.TreeSelectionMode
DeclarationTreeSelectionModeTreeProvider.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeSelectionMode before adapting it.TreeProviderContextValue
21 declared fieldsTreeProviderContextValueTreeProvider.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeProviderContextValue before adapting it.registry, expandedIds, selectedIds, selectionMode, showLines, showIcons, animateExpand, indent, variant, size, focusedId, tabbableId, isExpandedControlled, isSelectedControlled, setExpandedIds, setSelectedIds, toggleExpanded, selectNode, focusNode, getNodeDataTreeItemContextValue
4 declared fieldsTreeItemContextValueTreeProvider.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeItemContextValue before adapting it.nodeId, level, parentPath, isLastTreeProvider Props
14 declared fieldsTreeProviderPropsTreeProvider.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeProviderProps before adapting it.ResolveTreeIconOptions
7 declared fieldsResolveTreeIconOptionstree-icons.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ResolveTreeIconOptions before adapting it.stateTreeNodeRecord
9 declared fieldsTreeNodeRecordtree-registry.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeNodeRecord before adapting it.nodeId, parentId, disabled, hasChildren, data, element, order, isLast, levelTreeIconState
6 declared fieldsTreeIconStatetree-types.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeIconState before adapting it.nodeId, branch, expanded, selected, disabled, levelTreeIconRender
DeclarationTreeIconRendertree-types.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeIconRender before adapting it.TreeIconProp
DeclarationTreeIconProptree-types.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeIconProp before adapting it.TreeIcons
5 declared fieldsTreeIconstree-types.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of TreeIcons before adapting it.You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.