Tree View

A nested list that the user can expand and collapse, such as folders and files.

Project files

vite.config.ts
package.json
renovate.json
README.md

Usage

Code
import { TreeView } from '@leverui/components';
Code
<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 createTreeCollection from @leverui/components.

Shortcuts

TreeView.Node

Renders the whole tree. nodeState is an accessor. indentGuide is a function, so each branch gets its own element.

Code
<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:

Code
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)

vite.config.ts
package.json
renovate.json
README.md

Tree (size=sm)

vite.config.ts
package.json
renovate.json
README.md

Tree (size=md)

vite.config.ts
package.json
renovate.json
README.md

Variants

Use the variant prop to change the variant of the tree view.

Tree (variant=subtle)

vite.config.ts
package.json
renovate.json
README.md

Tree (variant=solid)

vite.config.ts
package.json
renovate.json
README.md

Colors

Use the colorPalette prop to change the color palette of the tree view.

Tree (colorPalette=gray)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=red)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=green)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=blue)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=teal)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=pink)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=purple)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=cyan)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=orange)

vite.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=yellow)

vite.config.ts
package.json
renovate.json
README.md

Disabled Node

Adding the disabled prop to a node's property will disable the node and prevent interaction.

Project files

vite.config.ts
package.json
renovate.json
README.md

Controlled Expansion

Use the expandedValue and onExpandedChange props to programmatically control node expansion behavior.

Project files

node_modules
solid-js
vite
vite.config.ts
package.json
renovate.json
README.md

Explicit Expand

Render the TreeView.BranchTrigger to manually control node expansion behavior.

You might need to set role="none" on the TreeView.BranchControl to avoid accessibility issues.

Project files

vite.config.ts
package.json
renovate.json
README.md

Expand Icon

Use the nodeState().expanded value to swap the rendered icon on the branch when it's expanded or collapsed.

Project files

vite.config.ts
package.json
renovate.json
README.md

Remove Indentation

Set the css variable --leverui-tree-indentation to 0px to remove the indentation of the tree view.

Project files

vite.config.ts
package.json
renovate.json
README.md

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

vite.config.ts
package.json
renovate.json
README.md

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

vite.config.ts
package.json
renovate.json
README.md

Collapse Animation

Use the animateContent prop to animate the tree view content expand/collapse state.

Project files

vite.config.ts
package.json
renovate.json
README.md

Expand/Collapse All

Provide controls to expand or collapse all nodes at once.

Project files

vite.config.ts
package.json
renovate.json
README.md

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

[]
vite.config.ts
package.json
renovate.json
README.md

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 Ctrl or ⌘ on macOS and click the items.
  • Click an item, then hold Shift while clicking on another item.

Project files

vite.config.ts
package.json
renovate.json
README.md

Checkbox Tree

Add checkboxes to tree nodes for selection functionality.

Project files

vite.config.ts
package.json
renovate.json
README.md

Mutation

Here's an example of how to design add/remove nodes in the tree view.

Project files

vite.config.ts
package.json
renovate.json
README.md

Custom Icon

Here's an example of how to render a custom icon for the tree view based on its data.

Tree

Footer

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

PropDefaultTypeDescription
collection (required)—TreeCollection<T>Collection of tree nodes.
expandOnClicktruebooleanOpen a branch on click.
selectionModesingle'multiple' | 'single'Select one node or several.
typeaheadtruebooleanType to jump to a matching node.
colorPalettegray'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'Color palette.
sizemd'md' | 'sm' | 'xs'Tree size.
variantsubtle'subtle' | 'solid'Tree style.
asdivNative tagHTML tag to render.
asChild—Solid render functionRender your own element with the root's props.
unstyled—booleanTurn 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—stringNode focused on first render.
defaultSelectedValue—string[]Nodes selected on first render.
expandedValue—string[]Ids of the expanded nodes, when you control them.
focusedValue—stringValue of the focused node.
ids—Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>Ids of the tree elements.
lazyMountfalsebooleanRender 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) => voidCalled when the checked nodes change.
onExpandedChange—(details: ExpandedChangeDetails<T>) => voidCalled when a branch opens or closes.
onFocusChange—(details: FocusChangeDetails<T>) => voidCalled when the focused node changes.
onLoadChildrenComplete—(details: LoadChildrenCompleteDetails<T>) => voidCalled when a node finishes loading its children.
onLoadChildrenError—(details: LoadChildrenErrorDetails<T>) => voidCalled when loading children fails.
onSelectionChange—(details: SelectionChangeDetails<T>) => voidCalled when the selection changes.
scrollToIndexFn—(details: ScrollToIndexDetails<T>) => voidScroll to an index. For virtualized trees.
selectedValue—string[]Selected nodes, when you control them.
translations—IntlTranslationsLocalized labels for screen readers.
unmountOnExitfalsebooleanRemove a branch's content when it closes.
animateContent—booleanAnimate branch content on expand and collapse.

Node

PropDefaultTypeDescription
render (required)—(props: NodeRenderProps) => JSX.ElementRender 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.ElementRender the indent guide inside each branch's content.
renderBranch—(props: NodeRenderProps) => JSX.ElementRender branch controls apart from render. Runs once per row.
branchProps—TreeViewBranchPropsProps for each TreeView.Branch.
branchContentProps—TreeViewBranchContentPropsProps 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.

Code
.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