# Tree View URL: https://ark-ui.com/docs/components/tree-view Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/tree-view.mdx A component that is used to show a tree hierarchy. --- ## Anatomy To set up the tree view component correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `TreeView` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' export const Basic = () => { return ( Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] | undefined } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show } from 'solid-js' export const Basic = () => { return ( Tree {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte Basic Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each} {#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### Controlled Expanded Pass the `expandedValue` and `onExpandedChange` props to the `TreeView.Root` component to control the expanded state of the tree view. **Example: controlled-expanded** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' import { useState } from 'react' export const ControlledExpanded = () => { const [expandedValue, setExpandedValue] = useState(['node_modules']) return ( setExpandedValue(expandedValue)} > Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show, createSignal } from 'solid-js' export const ControlledExpanded = () => { const [expandedValue, setExpandedValue] = createSignal(['node_modules']) return ( setExpandedValue(expandedValue)} > Tree {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each} {#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### Controlled Selection Pass the `selectedValue` and `onSelectionChange` props to the `TreeView.Root` component to control the selected state of the tree view. **Example: controlled-selected** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' import { useState } from 'react' export const ControlledSelected = () => { const [selectedValue, setSelectedValue] = useState(['package.json']) return ( setSelectedValue(selectedValue)} > Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show, createSignal } from 'solid-js' export const ControlledSelected = () => { const [selectedValue, setSelectedValue] = createSignal(['package.json']) return ( setSelectedValue(selectedValue)} > Tree {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte 
Selected: {JSON.stringify(selectedValue)}
Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each} {#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### Root Provider 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. **Example: root-provider** #### React ```tsx import { TreeView, createTreeCollection, useTreeView } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' export const RootProvider = () => { const treeView = useTreeView({ collection }) return ( Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] | undefined } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection, useTreeView } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show } from 'solid-js' export const RootProvider = () => { const treeView = useTreeView({ collection }) return ( Tree {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte Root Provider Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each} {#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` > If you're using the `RootProvider` component, you don't need to use the `Root` component. ### Lazy 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. **Example: async-loading** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon, LoaderCircleIcon } from 'lucide-react' import { useState } from 'react' import { useTreeViewNodeContext } from '../use-tree-view-node-context' // mock api result const response: Record = { node_modules: [ { id: 'zag-js', name: 'zag-js' }, { id: 'pandacss', name: 'panda' }, { id: '@types', name: '@types', childrenCount: 2 }, ], 'node_modules/@types': [ { id: 'react', name: 'react' }, { id: 'react-dom', name: 'react-dom' }, ], src: [ { id: 'app.tsx', name: 'app.tsx' }, { id: 'index.ts', name: 'index.ts' }, ], } // function to load children of a node function loadChildren(details: TreeView.LoadChildrenDetails): Promise { const value = details.valuePath.join('/') return new Promise((resolve) => { setTimeout(() => { resolve(response[value] ?? []) }, 1200) }) } export const AsyncLoading = () => { const [collection, setCollection] = useState(initialCollection) return ( setCollection(e.collection)} > Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } function TreeNodeIndicator() { const nodeState = useTreeViewNodeContext() return nodeState.loading ? : } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children || node.childrenCount ? ( {node.name} {node.children?.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] childrenCount?: number } const initialCollection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', childrenCount: 3 }, { id: 'src', name: 'src', childrenCount: 2 }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon, LoaderCircleIcon } from 'lucide-solid' import { For, createSignal } from 'solid-js' import { useTreeViewNodeContext } from '../use-tree-view-node-context' // mock api result const response: Record = { node_modules: [ { id: 'zag-js', name: 'zag-js' }, { id: 'pandacss', name: 'panda' }, { id: '@types', name: '@types', childrenCount: 2 }, ], 'node_modules/@types': [ { id: 'react', name: 'react' }, { id: 'react-dom', name: 'react-dom' }, ], src: [ { id: 'app.tsx', name: 'app.tsx' }, { id: 'index.ts', name: 'index.ts' }, ], } // function to load children of a node function loadChildren(details: TreeView.LoadChildrenDetails): Promise { const value = details.valuePath.join('/') return new Promise((resolve) => { setTimeout(() => { resolve(response[value] ?? []) }, 1200) }) } export const AsyncLoading = () => { const [collection, setCollection] = createSignal(initialCollection) return ( setCollection(e.collection)} > Tree {(node, index) => } ) } function TreeNodeIndicator() { const nodeState = useTreeViewNodeContext() return nodeState().loading ? : } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children || node.childrenCount ? ( {node.name} {(child, index) => } ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] childrenCount?: number } const initialCollection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', childrenCount: 3 }, { id: 'src', name: 'src', childrenCount: 2 }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte (collection = e.collection)}> Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render TreeNode(node, [index])} {/each} {#snippet TreeNodeIndicator()} {#snippet render(nodeState)} {#if nodeState().loading} {:else} {/if} {/snippet} {/snippet} {#snippet TreeNode(node: Node, indexPath: number[])} {#if node.children || node.childrenCount} {@render TreeNodeIndicator()} {node.name} {#each node.children ?? [] as child, index (child.id)} {@render TreeNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### Lazy Mount Lazy mounting is a feature that allows the content of a tree view to be rendered only when it is expanded. This is useful for performance optimization, especially when tree content is large or complex. To enable lazy mounting, use the `lazyMount` prop on the `TreeView.Root` component. In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tree view content when branches are collapsed, freeing up resources. The next time a branch is expanded, its content will be re-rendered. **Example: lazy-mount** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' export const LazyMount = () => { return ( Tree {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] | undefined } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show } from 'solid-js' interface Node { id: string name: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) export const LazyMount = () => { return ( Tree {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } ``` #### Vue ```vue ``` #### Svelte ```svelte Tree {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each} {#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### 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. **Example: filtering** #### React ```tsx import { useFilter } from '@ark-ui/react/locale' import { TreeView, createTreeCollection, useTreeViewContext } from '@ark-ui/react/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-react' import { useState } from 'react' export const Filtering = () => { const { contains } = useFilter({ sensitivity: 'base' }) const [collection, setCollection] = useState(initialCollection) const filter = (value: string) => { const filtered = value.length > 0 ? initialCollection.filter((node) => contains(node.name, value)) : initialCollection setCollection(filtered) } return (
filter(e.target.value)} /> {collection.rootNode.children?.map((node, index) => ( ))}
) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props const tree = useTreeViewContext() const nodeState = tree.getNodeState(props) return ( {nodeState.isBranch ? ( {node.name} {node.children?.map((child, index) => ( ))} ) : ( {node.name} )} ) } interface Node { id: string name: string children?: Node[] } const initialCollection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Solid ```tsx import { useFilter } from '@ark-ui/solid/locale' import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { SquareCheckBigIcon, ChevronRightIcon, FileIcon, FolderIcon } from 'lucide-solid' import { For, Show, createSignal } from 'solid-js' export const Filtering = () => { const filterFn = useFilter({ sensitivity: 'base' }) const [collection, setCollection] = createSignal(initialCollection) const filter = (value: string) => { const filtered = value.length > 0 ? initialCollection.filter((node) => filterFn().contains(node.name, value)) : initialCollection setCollection(filtered) } return (
filter(e.currentTarget.value)} /> {(node, index) => }
) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string children?: Node[] } const initialCollection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'node_modules', name: 'node_modules', children: [ { id: 'node_modules/zag-js', name: 'zag-js' }, { id: 'node_modules/pandacss', name: 'panda' }, { id: 'node_modules/@types', name: '@types', children: [ { id: 'node_modules/@types/react', name: 'react' }, { id: 'node_modules/@types/react-dom', name: 'react-dom' }, ], }, ], }, { id: 'src', name: 'src', children: [ { id: 'src/app.tsx', name: 'app.tsx' }, { id: 'src/index.ts', name: 'index.ts' }, ], }, { id: 'panda.config', name: 'panda.config.ts' }, { id: 'package.json', name: 'package.json' }, { id: 'renovate.json', name: 'renovate.json' }, { id: 'readme.md', name: 'README.md' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte
filter(e.currentTarget.value)} /> {#each collection.rootNode.children ?? [] as node, index (node.id)} {@render renderNode(node, [index])} {/each}
{#snippet renderNode(node: Node, indexPath: number[])} {#if node.children} {node.name} {#each node.children as child, index (child.id)} {@render renderNode(child, [...indexPath, index])} {/each} {:else} {node.name} {/if} {/snippet} ``` ### Links Tree items can be rendered as links to another page or website. This could be useful for documentation sites. Here's an example that modifies the tree collection to represent an hierarchical link structure. It uses the `asChild` prop to render the tree items as links, passing the `href` prop to a `` element. **Example: links** #### React ```tsx import { TreeView, createTreeCollection } from '@ark-ui/react/tree-view' import { ChevronRightIcon, ExternalLinkIcon, FileIcon } from 'lucide-react' export const Links = () => { return ( Docs {collection.rootNode.children?.map((node, index) => ( ))} ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( {node.children ? ( {node.name} {node.children.map((child, index) => ( ))} ) : ( {node.name} {node.href?.startsWith('http') && } )} ) } interface Node { id: string name: string href?: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'docs', name: 'Documentation', children: [ { id: 'docs/getting-started', name: 'Getting Started', href: '/docs/getting-started' }, { id: 'docs/installation', name: 'Installation', href: '/docs/installation' }, { id: 'docs/components', name: 'Components', children: [ { id: 'docs/components/accordion', name: 'Accordion', href: '/docs/components/accordion' }, { id: 'docs/components/dialog', name: 'Dialog', href: '/docs/components/dialog' }, { id: 'docs/components/menu', name: 'Menu', href: '/docs/components/menu' }, ], }, ], }, { id: 'examples', name: 'Examples', children: [ { id: 'examples/react', name: 'React Examples', href: '/examples/react' }, { id: 'examples/vue', name: 'Vue Examples', href: '/examples/vue' }, { id: 'examples/solid', name: 'Solid Examples', href: '/examples/solid' }, ], }, { id: 'external', name: 'External Links', children: [ { id: 'external/github', name: 'GitHub Repository', href: 'https://github.com/chakra-ui/zag' }, { id: 'external/npm', name: 'NPM Package', href: 'https://www.npmjs.com/package/@zag-js/core' }, { id: 'external/docs', name: 'Official Docs', href: 'https://zagjs.com' }, ], }, { id: 'readme.md', name: 'README.md', href: '/readme' }, { id: 'license', name: 'LICENSE', href: '/license' }, ], }, }) ``` #### Solid ```tsx import { TreeView, createTreeCollection } from '@ark-ui/solid/tree-view' import { ChevronRightIcon, ExternalLinkIcon, FileIcon } from 'lucide-solid' import { For, Show } from 'solid-js' export const Links = () => { return ( Docs {(node, index) => } ) } const TreeNode = (props: TreeView.NodeProviderProps) => { const { node, indexPath } = props return ( }> {node.name} } > {node.name} {(child, index) => } ) } interface Node { id: string name: string href?: string children?: Node[] } const collection = createTreeCollection({ nodeToValue: (node) => node.id, nodeToString: (node) => node.name, rootNode: { id: 'ROOT', name: '', children: [ { id: 'docs', name: 'Documentation', children: [ { id: 'docs/getting-started', name: 'Getting Started', href: '/docs/getting-started' }, { id: 'docs/installation', name: 'Installation', href: '/docs/installation' }, { id: 'docs/components', name: 'Components', children: [ { id: 'docs/components/accordion', name: 'Accordion', href: '/docs/components/accordion' }, { id: 'docs/components/dialog', name: 'Dialog', href: '/docs/components/dialog' }, { id: 'docs/components/menu', name: 'Menu', href: '/docs/components/menu' }, ], }, ], }, { id: 'examples', name: 'Examples', children: [ { id: 'examples/react', name: 'React Examples', href: '/examples/react' }, { id: 'examples/vue', name: 'Vue Examples', href: '/examples/vue' }, { id: 'examples/solid', name: 'Solid Examples', href: '/examples/solid' }, ], }, { id: 'external', name: 'External Links', children: [ { id: 'external/github', name: 'GitHub Repository', href: 'https://github.com/chakra-ui/zag' }, { id: 'external/npm', name: 'NPM Package', href: 'https://www.npmjs.com/package/@zag-js/core' }, { id: 'external/docs', name: 'Official Docs', href: 'https://zagjs.com' }, ], }, { id: 'readme.md', name: 'README.md', href: '/readme' }, { id: 'license', name: 'LICENSE', href: '/license' }, ], }, }) ``` #### Vue ```vue ``` #### Svelte ```svelte Docs {#each collection.rootNode.children ?? [] as node, index (node.id)} {/each} ``` ## Guides ### Type-Safety The `TreeView.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full type safety for tree nodes. This is particularly useful when building reusable tree view components with custom props and consistent styling. ```tsx import { TreeView as ArkTreeView, type TreeNode } from '@ark-ui/react/tree-view' import { createTreeCollection } from '@ark-ui/react/collection' interface TreeViewProps extends ArkTreeView.RootProps {} const TreeView: ArkTreeView.RootComponent = (props) => { return {/* ... */} } ``` Then, you can use the `TreeView` component as follows: ```tsx const App = () => { const collection = createTreeCollection({ initialItems: [ { id: '1', label: 'React', children: [] }, { id: '2', label: 'Vue', children: [] }, { id: '3', label: 'Svelte', children: [] }, ], }) return ( { // this will be strongly typed Array<{ id: string, label: string, children: [] }> console.log(e.value) }} > {/* ... */} ) } ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `TreeCollection` | Yes | The collection of tree nodes | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `checkedValue` | `string[]` | No | The controlled checked node value | | `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered. Use when you don't need to control the checked node value. | | `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered. Use when you don't need to control the expanded node value. | | `defaultFocusedValue` | `string` | No | The initial focused node value when rendered. Use when you don't need to control the focused node value. | | `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered. Use when you don't need to control the selected node value. | | `expandedValue` | `string[]` | No | The controlled expanded node ids | | `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not | | `focusedValue` | `string` | No | The value of the focused node | | `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loadChildren` | `(details: LoadChildrenDetails) => Promise` | No | Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding. | | `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes | | `onExpandedChange` | `(details: ExpandedChangeDetails) => void` | No | Called when the tree is opened or closed | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Called when the focused node changes | | `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails) => void` | No | Called when a node finishes loading children | | `onLoadChildrenError` | `(details: LoadChildrenErrorDetails) => void` | No | Called when loading children fails for one or more nodes | | `onSelectionChange` | `(details: SelectionChangeDetails) => void` | No | Called when the selection changes | | `selectedValue` | `string[]` | No | The controlled selected node value | | `selectionMode` | `'multiple' | 'single'` | No | Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected | | `typeahead` | `boolean` | No | Whether the tree supports typeahead search | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **BranchContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-content | | `[data-state]` | "open" | "closed" | | `[data-depth]` | The depth of the item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | **BranchControl Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-control | | `[data-path]` | The path of the item | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-value]` | The value of the item | | `[data-depth]` | The depth of the item | | `[data-loading]` | Present when loading | **BranchIndentGuide Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndentGuide Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indent-guide | | `[data-depth]` | The depth of the item | **BranchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-loading]` | Present when loading | **Branch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Branch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch | | `[data-depth]` | The depth of the item | | `[data-branch]` | | | `[data-value]` | The value of the item | | `[data-path]` | The path of the item | | `[data-selected]` | Present when selected | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-loading]` | Present when loading | **BranchText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-text | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-loading]` | Present when loading | **BranchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-trigger | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-value]` | The value of the item | | `[data-loading]` | Present when loading | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | | `[data-focus]` | Present when focused | | `[data-selected]` | Present when selected | | `[data-disabled]` | Present when disabled | | `[data-depth]` | The depth of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckboxIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `string | number | bigint | boolean | ReactElement> | Iterable | ReactPortal | Promise<...>` | No | | | `indeterminate` | `string | number | bigint | boolean | ReactElement> | Iterable | ReactPortal | Promise<...>` | No | | **NodeCheckbox Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckbox Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | node-checkbox | | `[data-state]` | "checked" | "unchecked" | "indeterminate" | | `[data-disabled]` | Present when disabled | **NodeProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `indexPath` | `number[]` | Yes | The index path of the tree node | | `node` | `NonNullable` | No | The tree node | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseTreeViewReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Tree Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `TreeCollection` | Yes | The collection of tree nodes | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `checkedValue` | `string[]` | No | The controlled checked node value | | `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered. Use when you don't need to control the checked node value. | | `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered. Use when you don't need to control the expanded node value. | | `defaultFocusedValue` | `string` | No | The initial focused node value when rendered. Use when you don't need to control the focused node value. | | `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered. Use when you don't need to control the selected node value. | | `expandedValue` | `string[]` | No | The controlled expanded node ids | | `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not | | `focusedValue` | `string` | No | The value of the focused node | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loadChildren` | `(details: LoadChildrenDetails) => Promise` | No | Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding. | | `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes | | `onExpandedChange` | `(details: ExpandedChangeDetails) => void` | No | Called when the tree is opened or closed | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Called when the focused node changes | | `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails) => void` | No | Called when a node finishes loading children | | `onLoadChildrenError` | `(details: LoadChildrenErrorDetails) => void` | No | Called when loading children fails for one or more nodes | | `onSelectionChange` | `(details: SelectionChangeDetails) => void` | No | Called when the selection changes | | `selectedValue` | `string[]` | No | The controlled selected node value | | `selectionMode` | `'multiple' | 'single'` | No | Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected | | `typeahead` | `boolean` | No | Whether the tree supports typeahead search | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **BranchContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-content | | `[data-state]` | "open" | "closed" | | `[data-depth]` | The depth of the item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | **BranchControl Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-control | | `[data-path]` | The path of the item | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-value]` | The value of the item | | `[data-depth]` | The depth of the item | | `[data-loading]` | Present when loading | **BranchIndentGuide Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndentGuide Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indent-guide | | `[data-depth]` | The depth of the item | **BranchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-loading]` | Present when loading | **Branch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Branch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch | | `[data-depth]` | The depth of the item | | `[data-branch]` | | | `[data-value]` | The value of the item | | `[data-path]` | The path of the item | | `[data-selected]` | Present when selected | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-loading]` | Present when loading | **BranchText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-text | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-loading]` | Present when loading | **BranchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-trigger | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-value]` | The value of the item | | `[data-loading]` | Present when loading | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | | `[data-focus]` | Present when focused | | `[data-selected]` | Present when selected | | `[data-disabled]` | Present when disabled | | `[data-depth]` | The depth of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'h3'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckboxIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `number | boolean | Node | (string & {}) | ArrayElement` | No | | | `indeterminate` | `number | boolean | Node | (string & {}) | ArrayElement` | No | | **NodeCheckbox Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckbox Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | node-checkbox | | `[data-state]` | "checked" | "unchecked" | "indeterminate" | | `[data-disabled]` | Present when disabled | **NodeProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `indexPath` | `number[]` | Yes | The index path of the tree node | | `node` | `NonNullable` | No | The tree node | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseTreeViewReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Tree Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `collection` | `TreeCollection` | Yes | The collection of tree nodes | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `checkedValue` | `string[]` | No | The controlled checked node values | | `defaultCheckedValue` | `string[]` | No | The initial checked node values when rendered. Use when you don't need to control the checked node values. | | `defaultExpandedValue` | `string[]` | No | The initial expanded node values when rendered. Use when you don't need to control the expanded node values. | | `defaultFocusedValue` | `string` | No | The initial focused node value when rendered. Use when you don't need to control the focused node value. | | `defaultSelectedValue` | `string[]` | No | The initial selected node values when rendered. Use when you don't need to control the selected node values. | | `expandedValue` | `string[]` | No | The controlled expanded node values | | `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not | | `focusedValue` | `string` | No | The id of the focused node | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; tree: string; label: string; node(value: string): string }>` | No | The ids of the tree elements. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loadChildren` | `(details: LoadChildrenDetails) => Promise` | No | A function that loads the children of a node. | | `selectedValue` | `string[]` | No | The controlled selected node values | | `selectionMode` | `'multiple' | 'single'` | No | Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected | | `typeahead` | `boolean` | No | Whether the tree supports typeahead search | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **BranchContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-content | | `[data-state]` | "open" | "closed" | | `[data-depth]` | The depth of the item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | **BranchControl Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-control | | `[data-path]` | The path of the item | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-value]` | The value of the item | | `[data-depth]` | The depth of the item | | `[data-loading]` | Present when loading | **BranchIndentGuide Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndentGuide Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indent-guide | | `[data-depth]` | The depth of the item | **BranchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-loading]` | Present when loading | **Branch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Branch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch | | `[data-depth]` | The depth of the item | | `[data-branch]` | | | `[data-value]` | The value of the item | | `[data-path]` | The path of the item | | `[data-selected]` | Present when selected | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-loading]` | Present when loading | **BranchText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-text | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-loading]` | Present when loading | **BranchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **BranchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-trigger | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-value]` | The value of the item | | `[data-loading]` | Present when loading | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | | `[data-focus]` | Present when focused | | `[data-selected]` | Present when selected | | `[data-disabled]` | Present when disabled | | `[data-depth]` | The depth of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckboxIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `{}` | No | | | `indeterminate` | `{}` | No | | **NodeCheckbox Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **NodeCheckbox Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | node-checkbox | | `[data-state]` | "checked" | "unchecked" | "indeterminate" | | `[data-disabled]` | Present when disabled | **NodeProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `indexPath` | `number[]` | Yes | The index path of the tree node | | `node` | `NonNullable` | No | The tree node | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `TreeViewApi` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Tree Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `checkedValue` | `string[]` | No | The controlled checked node value | | `collection` | `TreeCollection` | No | The tree collection data | | `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered. Use when you don't need to control the checked node value. | | `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered. Use when you don't need to control the expanded node value. | | `defaultFocusedValue` | `string` | No | The initial focused node value when rendered. Use when you don't need to control the focused node value. | | `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered. Use when you don't need to control the selected node value. | | `expandedValue` | `string[]` | No | The controlled expanded node ids | | `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not | | `focusedValue` | `string` | No | The value of the focused node | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `loadChildren` | `(details: LoadChildrenDetails) => Promise` | No | Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding. | | `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes | | `onExpandedChange` | `(details: ExpandedChangeDetails) => void` | No | Called when the tree is opened or closed | | `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Called when the focused node changes | | `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails) => void` | No | Called when a node finishes loading children | | `onLoadChildrenError` | `(details: LoadChildrenErrorDetails) => void` | No | Called when loading children fails for one or more nodes | | `onSelectionChange` | `(details: SelectionChangeDetails) => void` | No | Called when the selection changes | | `ref` | `Element` | No | | | `selectedValue` | `string[]` | No | The controlled selected node value | | `selectionMode` | `'multiple' | 'single'` | No | Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected | | `typeahead` | `boolean` | No | Whether the tree supports typeahead search | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **BranchContent Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'ul'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchContent Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-content | | `[data-state]` | "open" | "closed" | | `[data-depth]` | The depth of the item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | **BranchControl Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchControl Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-control | | `[data-path]` | The path of the item | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-value]` | The value of the item | | `[data-depth]` | The depth of the item | | `[data-loading]` | Present when loading | **BranchIndentGuide Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchIndentGuide Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indent-guide | | `[data-depth]` | The depth of the item | **BranchIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-indicator | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | | `[data-loading]` | Present when loading | **Branch Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'li'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Branch Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch | | `[data-depth]` | The depth of the item | | `[data-branch]` | | | `[data-value]` | The value of the item | | `[data-path]` | The path of the item | | `[data-selected]` | Present when selected | | `[data-state]` | "open" | "closed" | | `[data-disabled]` | Present when disabled | | `[data-loading]` | Present when loading | **BranchText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-text | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-loading]` | Present when loading | **BranchTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **BranchTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | branch-trigger | | `[data-disabled]` | Present when disabled | | `[data-state]` | "open" | "closed" | | `[data-value]` | The value of the item | | `[data-loading]` | Present when loading | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseTreeViewContext]>` | Yes | | **ItemIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemIndicator Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-indicator | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'li'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item | | `[data-path]` | The path of the item | | `[data-value]` | The value of the item | | `[data-focus]` | Present when focused | | `[data-selected]` | Present when selected | | `[data-disabled]` | Present when disabled | | `[data-depth]` | The depth of the item | **ItemText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | item-text | | `[data-disabled]` | Present when disabled | | `[data-selected]` | Present when selected | | `[data-focus]` | Present when focused | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'h3'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NodeCheckboxIndicator Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `fallback` | `Snippet<[]>` | No | | | `indeterminate` | `Snippet<[]>` | No | | **NodeCheckbox Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **NodeCheckbox Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | tree-view | | `[data-part]` | node-checkbox | | `[data-state]` | "checked" | "unchecked" | "indeterminate" | | `[data-disabled]` | Present when disabled | **NodeContext Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseTreeViewNodeContext]>` | Yes | | **NodeProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `indexPath` | `number[]` | Yes | | | `node` | `NonNullable` | No | | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseTreeViewReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `lazyMount` | `boolean` | No | Whether to enable lazy mounting | | `ref` | `Element` | No | | | `unmountOnExit` | `boolean` | No | Whether to unmount on exit. | **Tree Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'ul'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | ### Context These are the properties available when using `UtreeUview.Context`, `useUtreeUviewContext` hook or `useUtreeUview` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `collection` | `TreeCollection` | The tree collection data | | `expandedValue` | `string[]` | The value of the expanded nodes. | | `setExpandedValue` | `(value: string[]) => void` | Sets the expanded value | | `selectedValue` | `string[]` | The value of the selected nodes. | | `setSelectedValue` | `(value: string[]) => void` | Sets the selected value | | `checkedValue` | `string[]` | The value of the checked nodes | | `toggleChecked` | `(value: string, isBranch: boolean) => void` | Toggles the checked value of a node | | `setChecked` | `(value: string[]) => void` | Sets the checked value of a node | | `clearChecked` | `VoidFunction` | Clears the checked value of a node | | `getCheckedMap` | `() => CheckedValueMap` | Returns the checked details of branch and leaf nodes | | `getVisibleNodes` | `() => V[]` | Returns the visible nodes as a flat array of nodes and their index path | | `expand` | `(value?: string[]) => void` | Function to expand nodes. If no value is provided, all nodes will be expanded | | `collapse` | `(value?: string[]) => void` | Function to collapse nodes If no value is provided, all nodes will be collapsed | | `select` | `(value?: string[]) => void` | Function to select nodes If no value is provided, all nodes will be selected | | `deselect` | `(value?: string[]) => void` | Function to deselect nodes If no value is provided, all nodes will be deselected | | `focus` | `(value: string) => void` | Function to focus a node by value | | `selectParent` | `(value: string) => void` | Function to select the parent node of the focused node | | `expandParent` | `(value: string) => void` | Function to expand the parent node of the focused node | ## Accessibility Complies with the [Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/). ### Keyboard Support