Tree
Tree is a component used to display hierarchical data structures in an expandable tree format.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs">
<Tree.Item label="node_modules">
<Tree.Item label="react" />
<Tree.Item label="react-dom" />
<Tree.Item label="@yamada-ui">
<Tree.Item label="react" />
<Tree.Item label="utils" />
</Tree.Item>
</Tree.Item>
<Tree.Item label="src">
<Tree.Item label="components">
<Tree.Item label="tree.tsx" />
<Tree.Item label="index.ts" />
</Tree.Item>
<Tree.Item label="app">
<Tree.Item label="about">
<Tree.Item label="layout.tsx" />
<Tree.Item label="page.tsx" />
</Tree.Item>
<Tree.Item label="layout.tsx" />
<Tree.Item label="page.tsx" />
</Tree.Item>
</Tree.Item>
<Tree.Item label="pnpm-lock.yaml" />
<Tree.Item label="package.json" />
<Tree.Item label="tsconfig.json" />
<Tree.Item label="README.md" />
</Tree.Root>
Usage
import { Tree } from "@yamada-ui/react"
import { Tree } from "@/components/ui"
import { Tree } from "@workspaces/ui"
<Tree.Root>
<Tree.Item>
<Tree.Item />
</Tree.Item>
<Tree.Item />
</Tree.Root>
If the
label of Tree.Item is a string, you can omit the value.Use items
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const items = useMemo<Tree.ItemType[]>(
() => [
{
children: [
{ label: "react" },
{ label: "react-dom" },
{
children: [{ label: "react" }, { label: "utils" }],
label: "@yamada-ui",
},
],
label: "node_modules",
},
{
children: [
{
children: [{ label: "tree.tsx" }, { label: "index.ts" }],
label: "components",
},
{
children: [
{
children: [{ label: "layout.tsx" }, { label: "page.tsx" }],
label: "about",
},
{ label: "layout.tsx" },
{ label: "page.tsx" },
],
label: "app",
},
],
label: "src",
},
{ label: "pnpm-lock.yaml" },
{ label: "package.json" },
{ label: "tsconfig.json" },
{ label: "README.md" },
],
[],
)
return <Tree.Root maxW="2xs" items={items} />
Change Variant
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<VStack>
<For each={["subtle", "solid"]}>
{(variant, index) => (
<Tree.Root
key={index}
maxW="2xs"
variant={variant}
defaultSelectedValue="node_modules"
items={treeItems}
/>
)}
</For>
</VStack>
Change Size
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<VStack>
<For each={["sm", "md", "lg"]}>
{(size, index) => (
<Tree.Root
key={index}
maxW="2xs"
size={size}
defaultExpandedValue={["src"]}
defaultSelectedValue="node_modules"
items={treeItems}
/>
)}
</For>
</VStack>
Change Shape
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<VStack>
<For each={["rounded", "square", "circle"]}>
{(shape, index) => (
<Tree.Root
key={index}
maxW="2xs"
defaultSelectedValue="node_modules"
items={treeItems}
shape={shape}
/>
)}
</For>
</VStack>
Set Default Expanded Items
To have specific items expanded by default, set the item values to defaultExpandedValue.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root
maxW="2xs"
defaultExpandedValue={["src", "src/components"]}
items={treeItems}
/>
Set Default Selected Item
To have a specific item selected by default, set the item value to defaultSelectedValue.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" defaultSelectedValue="node_modules" items={treeItems} />
Select Multiple Items
To select multiple items, set multiple to true.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" items={treeItems} multiple />
Enable Checkboxes
To enable checkboxes for items, set checkable to true.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" checkable items={treeItems} />
Set Default Checked Items
To have specific items checked by default, set the item values to defaultCheckedValue.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root
maxW="2xs"
checkable
defaultCheckedValue={["package.json"]}
items={treeItems}
/>
Disable an Item
To disable a specific item, set disabled.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const items = useMemo<Tree.ItemType[]>(
() => [
{
children: [
{ label: "react" },
{ label: "react-dom" },
{
children: [{ label: "react" }, { label: "utils" }],
label: "@yamada-ui",
},
],
disabled: true,
label: "node_modules",
},
{
children: [
{
children: [{ label: "tree.tsx" }, { label: "index.ts" }],
label: "components",
},
{
children: [
{
children: [{ label: "layout.tsx" }, { label: "page.tsx" }],
label: "about",
},
{ label: "layout.tsx" },
{ label: "page.tsx" },
],
label: "app",
},
],
label: "src",
},
{ disabled: true, label: "pnpm-lock.yaml" },
{ label: "package.json" },
{ label: "tsconfig.json" },
{ label: "README.md" },
],
[],
)
return <Tree.Root maxW="2xs" items={items} />
Use as Link
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const items = useMemo<Tree.ItemType[]>(
() => [
{
children: [
{ label: "react" },
{ label: "react-dom" },
{
children: [{ label: "react" }, { label: "utils" }],
label: "@yamada-ui",
},
],
label: "node_modules",
},
{
children: [
{
children: [{ label: "tree.tsx" }, { label: "index.ts" }],
label: "components",
},
{
children: [
{
children: [{ label: "layout.tsx" }, { label: "page.tsx" }],
label: "about",
},
{ label: "layout.tsx" },
{ label: "page.tsx" },
],
label: "app",
},
],
label: "src",
},
{ label: "pnpm-lock.yaml" },
{ label: "package.json" },
{ label: "tsconfig.json" },
{
as: "a",
href: "https://yamada-ui.com",
rel: "noopener",
target: "_blank",
endElement: <SquareArrowOutUpRightIcon />,
label: "README.md",
},
],
[],
)
return <Tree.Root maxW="2xs" items={items} />
Show Guide Line
To show guide lines, set withGuideLine to true.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" items={treeItems} withGuideLine />
Hide Indicator
To hide the indicator, set indicatorHidden to true.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" indicatorHidden items={treeItems} />
Add Animation
To add animation when expanding and collapsing, set animated to true.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" animated items={treeItems} />
Filtering
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const [items, setItems] = useState<Tree.ItemType[]>(treeItems)
const searchItems = useCallback(
(value: string, items: Tree.ItemType[]): Tree.ItemType[] => {
if (!value.length) return items
return items
.map((item) => {
if ("children" in item) {
if (isString(item.label) && match(item.label, value)) {
return item
} else {
const children = searchItems(value, item.children)
if (children.length) return { ...item, children }
}
} else if (isString(item.label) && match(item.label, value)) {
return item
}
})
.filter((item) => !isUndefined(item))
},
[],
)
return (
<VStack gap="sm" maxW="2xs">
<Input
placeholder="Search"
onChange={(ev) => {
setItems(searchItems(ev.target.value, treeItems))
}}
/>
<Tree.Root items={items} />
</VStack>
)
If you use this code, you need to add
"use client" to the top of the file.Async Loading
To load child items asynchronously, use asyncChildren instead of children.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const items = useMemo<Tree.ItemType[]>(
() => [
{
asyncChildren: async () => {
await wait(1000)
return [
{ label: "react" },
{ label: "react-dom" },
{
children: [{ label: "react" }, { label: "utils" }],
label: "@yamada-ui",
},
]
},
label: "node_modules",
},
{
children: [
{
children: [{ label: "tree.tsx" }, { label: "index.ts" }],
label: "components",
},
{
children: [
{
children: [{ label: "layout.tsx" }, { label: "page.tsx" }],
label: "about",
},
{ label: "layout.tsx" },
{ label: "page.tsx" },
],
label: "app",
},
],
label: "src",
},
{ label: "pnpm-lock.yaml" },
{ label: "package.json" },
{ label: "tsconfig.json" },
{ label: "README.md" },
],
[],
)
return <Tree.Root maxW="2xs" items={items} />
If you use this code, you need to add
"use client" to the top of the file.Change Loading Scheme
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const items = useMemo<Tree.ItemType[]>(
() => [
{
asyncChildren: async () => {
await wait(1000)
return [
{ label: "react" },
{ label: "react-dom" },
{
children: [{ label: "react" }, { label: "utils" }],
label: "@yamada-ui",
},
]
},
label: "node_modules",
},
{
children: [
{
children: [{ label: "tree.tsx" }, { label: "index.ts" }],
label: "components",
},
{
children: [
{
children: [{ label: "layout.tsx" }, { label: "page.tsx" }],
label: "about",
},
{ label: "layout.tsx" },
{ label: "page.tsx" },
],
label: "app",
},
],
label: "src",
},
{ label: "pnpm-lock.yaml" },
{ label: "package.json" },
{ label: "tsconfig.json" },
{ label: "README.md" },
],
[],
)
return <Tree.Root maxW="2xs" items={items} loadingScheme="dots" />
If you use this code, you need to add
"use client" to the top of the file.Expand/Collapse All
To expand or collapse all items, use controlRef.
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const controlRef = useRef<Tree.Control>(null)
return (
<VStack gap="md">
<ButtonGroup.Root>
<ButtonGroup.Item onClick={() => controlRef.current?.expand()}>
Expand All
</ButtonGroup.Item>
<ButtonGroup.Item onClick={() => controlRef.current?.collapse()}>
Collapse All
</ButtonGroup.Item>
</ButtonGroup.Root>
<Tree.Root maxW="2xs" controlRef={controlRef} items={treeItems} />
</VStack>
)
If you use this code, you need to add
"use client" to the top of the file.Customize Element
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root
maxW="2xs"
items={treeItems}
startElement={{
group: ({ expanded }) =>
expanded ? <FolderOpenIcon /> : <FolderClosedIcon />,
item: <FileIcon />,
}}
/>
If you use this code, you need to add
"use client" to the top of the file.- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root maxW="2xs" endElement={<LockKeyholeIcon />} items={treeItems} />
Customize Indicator
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
<Tree.Root
maxW="2xs"
indicator={({ expanded }) =>
expanded ? <SquareMinusIcon /> : <SquarePlusIcon />
}
items={treeItems}
indicatorProps={{ _expanded: { transform: "rotate(0deg)" } }}
/>
If you use this code, you need to add
"use client" to the top of the file.Control
- node_modules
- src
- pnpm-lock.yaml
- package.json
- tsconfig.json
- README.md
const [selectedValue, setSelectedValue] = useState<string>("package.json")
const [checkedValue, setCheckedValue] = useState<string[]>(["README.md"])
const [expandedValue, setExpandedValue] = useState<string[]>(["node_modules"])
return (
<Tree.Root
maxW="2xs"
checkable
checkedValue={checkedValue}
expandedValue={expandedValue}
items={treeItems}
selectedValue={selectedValue}
onCheckedChange={setCheckedValue}
onExpandedChange={setExpandedValue}
onSelectedChange={setSelectedValue}
/>
)
If you use this code, you need to add
"use client" to the top of the file.Props
Accessibility
Tree follows the WAI-ARIA - TreeView Pattern for accessibility.
When aria-label is set, it will be read aloud by screen readers.
<Tree.Root aria-label="File tree" />
Keyboard Navigation
| Key | Description | State |
|---|---|---|
Tab | Focuses on the selected item or the first item. | - |
ArrowUp | Focuses the previous enabled item. | - |
Shift + ArrowUp | Focuses the previous enabled item and selects it. | multiple={true} |
Control + Shift + ArrowUp | Collapses all items. | - |
ArrowDown | Focuses the next enabled item. | - |
Shift + ArrowDown | Focuses the next enabled item and selects it. | multiple={true} |
Control + Shift + ArrowDown | Expands all items. | - |
ArrowRight | If the focused item is collapsed, expands it. If expanded, focuses the first child item. | - |
ArrowLeft | If the focused item is expanded, collapses it. If collapsed, focuses the parent item. | - |
Space, Enter | Selects the focused item. If it's a group item, toggles its expansion/collapse. | - |
Shift + Space, Enter | Selects all items between the first selected item and the currently focused item. | multiple={true} |
Home | Focuses the first enabled item. | - |
End | Focuses the last enabled item. | - |
Control + A | Selects all enabled items. | multiple={true} |
a-z, A-Z | Focuses expanded item whose label starts with the typed character(s). | - |
ARIA Roles and Attributes
| Component | Role and Attributes | Usage |
|---|---|---|
Tree.Root | role="tree" | Indicates that the element is a tree. |
aria-multiselectable | Set to "true" when multiple={true} or checkable={true}. | |
Tree.Item | role="treeitem" | Indicates that the element is a tree item. |
aria-expanded | Set to "true" when the item is expanded, "false" when collapsed. | |
aria-selected | Set to "true" when the item is selected. | |
aria-disabled | Set to "true" when the item is disabled. | |
aria-level | Sets the hierarchy level of the item. | |
aria-labelledby | Sets the id of the related Tree.Item > div > span. | |
Tree.Item > ul | role="group" | Indicates that the element is a group. |
aria-labelledby | Sets the id of the related Tree.Item > div > span. | |
aria-busy | Set to "true" when the item's children are loading. | |
Tree.Item > div > input | id | Used to associate with the parent Tree.Item > div > input. |
aria-controls | Sets the id of related child Tree.Item > div > input elements. | |
aria-labelledby | Sets the id of the related Tree.Item > div > span. | |
Tree.Item > div > span | id | Used to associate Tree.Item, Tree.Item > ul, and Tree.Item > div > input. |
Similar Components
DataList
DataList is used to display a list of data items.
List
List is a component for displaying lists. By default, it renders a ul element.
NativeAccordion
NativeAccordion is a component for a list that displays information in an expandable or collapsible manner using the HTML details element.
Accordion
Accordion is a component for a list that displays information in an expandable or collapsible manner.
Timeline
Timeline is a component that is used to display a list of events in chronological order.
Tabs
Tabs is a component for switching between different display areas.
NativeTable
NativeTable is a component for efficiently organizing and displaying data.
Sidebar
Sidebar is a component used to display a list of items in a sidebar.
Uses Components & Hooks
Checkbox
Checkbox is a component used for allowing users to select multiple values from multiple options.
Collapse
Collapse is a component that allows you to expand or collapse an element for display.
Loading
Loading is a component displayed during waiting times, such as when data is being loaded.
Motion
Motion is a convenient component that extends the Yamada UI Style Props to Motion.
Icon
Icon is a general icon component that can be used in your projects.
useDescendants
useDescendants is a custom hook that manages descendants.
useDisclosure
useDisclosure is a custom hook that helps handle common open/close or toggle scenarios. It can be used to control components such as Modal, Dialog, Drawer, etc.
useAsyncCallback
useAsyncCallback is a custom hook for managing asynchronous callbacks.