Tree View
A nested list that the user can expand and collapse, such as folders and files.
Project files
Usage
import { TreeView } from '@leverui/components';
<TreeView.Root>
<TreeView.Label />
<TreeView.Tree>
<TreeView.Branch>
<TreeView.BranchControl>
<TreeView.BranchIndicator />
<TreeView.BranchText />
</TreeView.BranchControl>
<TreeView.BranchContent>
<TreeView.BranchIndentGuide />
<TreeView.Item />
</TreeView.BranchContent>
</TreeView.Branch>
<TreeView.Item />
</TreeView.Tree>
</TreeView.Root>
Pass your tree data to
createTreeCollectionfrom@leverui/components.
Shortcuts
TreeView.Node
Renders the whole tree. nodeState is an accessor. indentGuide is a
function, so each branch gets its own element.
<TreeView.Node
indentGuide={() => <TreeView.BranchIndentGuide />}
render={({ node, nodeState }) =>
nodeState().isBranch ? (
<TreeView.BranchControl>
<TreeView.BranchText>{node.name}</TreeView.BranchText>
</TreeView.BranchControl>
) : (
<TreeView.Item>
<TreeView.ItemText>{node.name}</TreeView.ItemText>
</TreeView.Item>
)
}
/>
Same as:
function TreeNode(props: TreeView.NodeProviderProps<Node>) {
return (
<TreeView.NodeProvider node={props.node} indexPath={props.indexPath}>
{props.node.children ? (
<TreeView.Branch>
<TreeView.BranchControl>
<TreeView.BranchText>{props.node.name}</TreeView.BranchText>
</TreeView.BranchControl>
<TreeView.BranchContent>
<TreeView.BranchIndentGuide />
<For each={props.node.children}>
{(child, index) => (
<TreeNode node={child} indexPath={[...props.indexPath, index()]} />
)}
</For>
</TreeView.BranchContent>
</TreeView.Branch>
) : (
<TreeView.Item>
<TreeView.ItemText>{props.node.name}</TreeView.ItemText>
</TreeView.Item>
)}
</TreeView.NodeProvider>
);
}
Examples
Sizes
Use the size prop to change the size of the tree view.
Tree (size=xs)
Tree (size=sm)
Tree (size=md)
Variants
Use the variant prop to change the variant of the tree view.
Tree (variant=subtle)
Tree (variant=solid)
Colors
Use the colorPalette prop to change the color palette of the tree view.
Tree (colorPalette=gray)
Tree (colorPalette=red)
Tree (colorPalette=green)
Tree (colorPalette=blue)
Tree (colorPalette=teal)
Tree (colorPalette=pink)
Tree (colorPalette=purple)
Tree (colorPalette=cyan)
Tree (colorPalette=orange)
Tree (colorPalette=yellow)
Disabled Node
Adding the disabled prop to a node's property will disable the node and prevent interaction.
Project files
Controlled Expansion
Use the expandedValue and onExpandedChange props to programmatically control node expansion behavior.
Project files
Explicit Expand
Render the TreeView.BranchTrigger to manually control node expansion behavior.
You might need to set
role="none"on theTreeView.BranchControlto avoid accessibility issues.
Project files
Expand Icon
Use the nodeState().expanded value to swap the rendered icon on the branch when it's expanded or collapsed.
Project files
Remove Indentation
Set the css variable --leverui-tree-indentation to 0px to remove the indentation of the tree view.
Project files
Async Loading
Lazy loading is a feature that allows the tree view to load children of a node on demand (or async). This helps to improve the initial load time and memory usage.
To use this, you need to provide the following:
loadChildren— A function that is used to load the children of a node.onLoadChildrenComplete— A callback that is called when the children of a node are loaded. Used to update the tree collection.childrenCount— A number that indicates the number of children of a branch node.
Project files
Filtering
Filtering is useful when you have a large tree and you want to filter the nodes to only show the ones that match the search query.
Here's an example that composes the filter method from the TreeCollection and useFilter hook to filter the nodes.
Tree
Collapse Animation
Use the animateContent prop to animate the tree view content expand/collapse state.
Project files
Expand/Collapse All
Provide controls to expand or collapse all nodes at once.
Project files
Store
Use the useTreeView hook to create the tree view store and pass it to the TreeView.RootProvider component. This allows you to have maximum control over the tree view programmatically.
Project files
[]
Links
Render the tree items as links by leveraging the asChild prop on the TreeView.Item component.
Multi Select
Add the selectionMode="multiple" prop to the TreeView.Root component to enable multi-select functionality.
This mode requires a modifier key to be pressed to select multiple items.
- Hold
Ctrlor⌘on macOS and click the items.- Click an item, then hold
Shiftwhile clicking on another item.
Project files
Checkbox Tree
Add checkboxes to tree nodes for selection functionality.
Project files
Mutation
Here's an example of how to design add/remove nodes in the tree view.
Project files
Custom Icon
Here's an example of how to render a custom icon for the tree view based on its data.
Tree
Guides
Collections and state
Each node needs a value that stays the same. To control the state, use
selectedValue with onSelectionChange, and expandedValue with
onExpandedChange. Keep a visible label on the tree. Do not rely on color alone
to show that a node is disabled.
Props
Root
| Prop | Default | Type | Description |
|---|---|---|---|
collection (required) | — | TreeCollection<T> | Collection of tree nodes. |
expandOnClick | true | boolean | Open a branch on click. |
selectionMode | single | 'multiple' | 'single' | Select one node or several. |
typeahead | true | boolean | Type to jump to a matching node. |
colorPalette | gray | 'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink' | Color palette. |
size | md | 'md' | 'sm' | 'xs' | Tree size. |
variant | subtle | 'subtle' | 'solid' | Tree style. |
as | div | Native tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the root's props. |
unstyled | — | boolean | Turn off the Lever UI styles. |
checkedValue | — | string[] | Checked nodes, when you control them. |
defaultCheckedValue | — | string[] | Nodes checked on first render. |
defaultExpandedValue | — | string[] | Ids of the nodes expanded on first render. |
defaultFocusedValue | — | string | Node focused on first render. |
defaultSelectedValue | — | string[] | Nodes selected on first render. |
expandedValue | — | string[] | Ids of the expanded nodes, when you control them. |
focusedValue | — | string | Value of the focused node. |
ids | — | Partial<{ root: string; tree: string; label: string; node: (value: string) => string }> | Ids of the tree elements. |
lazyMount | false | boolean | Render a branch's content on first open. |
loadChildren | — | (details: LoadChildrenDetails<T>) => Promise<T[]> | Load a node's children. The branch expands once the promise resolves. |
onCheckedChange | — | (details: CheckedChangeDetails) => void | Called when the checked nodes change. |
onExpandedChange | — | (details: ExpandedChangeDetails<T>) => void | Called when a branch opens or closes. |
onFocusChange | — | (details: FocusChangeDetails<T>) => void | Called when the focused node changes. |
onLoadChildrenComplete | — | (details: LoadChildrenCompleteDetails<T>) => void | Called when a node finishes loading its children. |
onLoadChildrenError | — | (details: LoadChildrenErrorDetails<T>) => void | Called when loading children fails. |
onSelectionChange | — | (details: SelectionChangeDetails<T>) => void | Called when the selection changes. |
scrollToIndexFn | — | (details: ScrollToIndexDetails<T>) => void | Scroll to an index. For virtualized trees. |
selectedValue | — | string[] | Selected nodes, when you control them. |
translations | — | IntlTranslations | Localized labels for screen readers. |
unmountOnExit | false | boolean | Remove a branch's content when it closes. |
animateContent | — | boolean | Animate branch content on expand and collapse. |
Node
| Prop | Default | Type | Description |
|---|---|---|---|
render (required) | — | (props: NodeRenderProps) => JSX.Element | Render a branch control or a leaf item. Gets node, indexPath, and the nodeState accessor. Runs once per row, so call nodeState() inside the JSX. |
indentGuide | — | () => JSX.Element | Render the indent guide inside each branch's content. |
renderBranch | — | (props: NodeRenderProps) => JSX.Element | Render branch controls apart from render. Runs once per row. |
branchProps | — | TreeViewBranchProps | Props for each TreeView.Branch. |
branchContentProps | — | TreeViewBranchContentProps | Props for each TreeView.BranchContent. |
Customize with CSS
size, variant, and animateContent take a value per screen size. Pass an
object with the keys base, sm, md, lg, xl, and 2xl. The root and
every part accept class and style. Set unstyled on the root or on one
part to turn off its default styles.
Each part has a fixed class, such as .leverui-tree-view__item or
.leverui-tree-view__branchControl.
.project-tree {
--leverui-tree-indent-size: 1.5rem;
--leverui-tree-indentation: 2rem;
--leverui-tree-icon-size: 1rem;
--leverui-tree-padding-inline: 0.75rem;
--leverui-tree-padding-block: 0.4rem;
--leverui-tree-item-gap: 0.5rem;
}
.project-tree .leverui-tree-view__item[data-selected] {
font-weight: 600;
}
Add class="project-tree" to TreeView.Root. Load your CSS after the default
stylesheet.
Explorer
Click a part name in the sidebar to highlight it in the preview.
Component Anatomy
Hover to highlight, click to select parts