---
title: Tree
description: "`Tree` is a component used to display hierarchical data structures in an expandable tree format."
links:
- style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/tree/tree.style.ts
- source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/tree
- storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-tree--basic
---
# Tree
`Tree` is a component used to display hierarchical data structures in an expandable tree format.
```tsx
```
## Usage
```tsx
import { Tree } from "@yamada-ui/react"
```
```tsx
import { Tree } from "@/components/ui"
```
```tsx
import { Tree } from "@workspaces/ui"
```
```tsx
```
:::tip
If the `label` of `Tree.Item` is a string, you can omit the `value`.
:::
### Use items
```tsx
const items = useMemo(
() => [
{
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
```
### Change Variant
```tsx
{(variant, index) => (
)}
```
### Change Size
```tsx
{(size, index) => (
)}
```
### Change Shape
```tsx
{(shape, index) => (
)}
```
### Set Default Expanded Items
To have specific items expanded by default, set the item values to `defaultExpandedValue`.
```tsx
```
### Set Default Selected Item
To have a specific item selected by default, set the item value to `defaultSelectedValue`.
```tsx
```
### Select Multiple Items
To select multiple items, set `multiple` to `true`.
```tsx
```
### Enable Checkboxes
To enable checkboxes for items, set `checkable` to `true`.
```tsx
```
### Set Default Checked Items
To have specific items checked by default, set the item values to `defaultCheckedValue`.
```tsx
```
### Disable an Item
To disable a specific item, set `disabled`.
```tsx
const items = useMemo(
() => [
{
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
```
### Use as Link
```tsx
const items = useMemo(
() => [
{
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: ,
label: "README.md",
},
],
[],
)
return
```
### Show Guide Line
To show guide lines, set `withGuideLine` to `true`.
```tsx
```
### Hide Indicator
To hide the indicator, set `indicatorHidden` to `true`.
```tsx
```
### Add Animation
To add animation when expanding and collapsing, set `animated` to `true`.
```tsx
```
### Filtering
```tsx
const [items, setItems] = useState(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 (
{
setItems(searchItems(ev.target.value, treeItems))
}}
/>
)
```
### Async Loading
To load child items asynchronously, use `asyncChildren` instead of `children`.
```tsx
const items = useMemo(
() => [
{
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
```
### Change Loading Scheme
```tsx
const items = useMemo(
() => [
{
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
```
### Expand/Collapse All
To expand or collapse all items, use `controlRef`.
```tsx
const controlRef = useRef(null)
return (
controlRef.current?.expand()}>
Expand All
controlRef.current?.collapse()}>
Collapse All
)
```
### Customize Element
```tsx
expanded ? : ,
item: ,
}}
/>
```
```tsx
} items={treeItems} />
```
### Customize Indicator
```tsx
expanded ? :
}
items={treeItems}
indicatorProps={{ _expanded: { transform: "rotate(0deg)" } }}
/>
```
### Control
```tsx
const [selectedValue, setSelectedValue] = useState("package.json")
const [checkedValue, setCheckedValue] = useState(["README.md"])
const [expandedValue, setExpandedValue] = useState(["node_modules"])
return (
)
```
## Props
### Tree.Root
| Prop | Default | Type | Description |
| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `as` | - | `As` | The HTML element to render. |
| `asChild` | - | `boolean` | Merges its props onto its immediate child. |
| `css` | - | `CSSObject \| CSSObject[]` | The CSS object. |
| `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. |
| `size` | `"md"` | `"lg" \| "md" \| "sm"` | The size of the component. |
| `variant` | `"subtle"` | `"solid" \| "subtle"` | The variant of the component. |
| `animated` | `false` | `boolean` | If `true`, the tree item will be animated. |
| `checkable` | `false` | `boolean` | If `true`, the tree will allow checkable items. |
| `checkboxProps` | - | `Omit, "value" \| "defaultChecked" \| "checked">` | Props for the checkbox component. |
| `checkedValue` | - | `string[]` | The checked value of the tree. |
| `controlRef` | - | `RefObject` | Ref of the tree callbacks. |
| `defaultCheckedValue` | - | `string[]` | The initial checked value of the tree. |
| `defaultExpandedValue` | - | `string[]` | The initial expanded value of the tree. |
| `defaultSelectedValue` | - | `Multiple extends true ? string[] : string` | The initial selected value of the tree. |
| `endElement` | - | `string \| number \| bigint \| boolean \| ReactElement> \| Iterable \| ... 4 more ... \| { ...; }` | The element to display at the end of the item. |
| `endElementProps` | - | `TreeEndElementProps` | Props for the end component. |
| `expandedValue` | - | `string[]` | The expanded value of the tree. |
| `groupProps` | - | `Omit` | Props for the group component. |
| `indicator` | - | `string \| number \| bigint \| boolean \| ReactElement> \| Iterable \| ReactPortal \| Promise<...> \| ((props: TreeCallBackProps) => ReactNode)` | The tree indicator icon to use. |
| `indicatorHidden` | `false` | `boolean` | If `true`, hide the tree indicator icon for all items. |
| `indicatorProps` | - | `TreeIndicatorProps` | Props for the indicator component. |
| `itemProps` | - | `Omit< |
TreeItemProps,
"children" \| "label" \| "open" \| "query" \| "value"
> `| Props for the item component. |
|`items`| - |`TreeItem[]`| If provided, generate elements based on items. |
|`labelProps`| - |`TreeLabelProps`| Props for the label component. |
|`loadingScheme`|`"oval"`|`LoadingScheme`| The loading scheme. |
|`multiple`|`false`|`Multiple`| If`true`, the tree will allow multiple selection. |
| `onCheckedChange`| - |`(value: string[]) => void`| The callback invoked when checked value changes. |
|`onExpandedChange`| - |`(value: string[]) => void`| The callback invoked when expanded value changes. |
|`onSelectedChange`| - |`(value: Multiple extends true ? string[] : string) => void`| The callback invoked when selected value changes. |
|`selectedValue`| - |`Multiple extends true ? string[] : string`| The selected value of the tree. |
|`startElement`| - |`string \| number \| bigint \| boolean \| ReactElement> \| Iterable \| ... 4 more ... \| { ...; }`| The element to display at the start of the item. |
|`startElementProps`| - |`TreeStartElementProps` | Props for the start component. |
### Tree.Item
| Prop | Default | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `as` | - | `As` | The HTML element to render. |
| `asChild` | - | `boolean` | Merges its props onto its immediate child. |
| `css` | - | `CSSObject \| CSSObject[]` | The CSS object. |
| `colorScheme` | - | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables. |
| `animated` | `false` | `boolean` | If `true`, the tree item will be animated. |
| `asyncChildren` | - | `() => Promise` | If provided, the tree item will be rendered as an async tree item. |
| `checkboxProps` | - | `Omit` | Props for the checkbox component. |
| `defaultOpen` | - | `boolean` | If `true`, the element will be initially opened. |
| `disabled` | `false` | `boolean` | If `true`, the tree item will be disabled. |
| `endElement` | - | `TreeItemReactNode` | The element to display at the end of the item. |
| `endElementProps` | - | `TreeEndElementProps` | Props for the end component. |
| `groupProps` | - | `Omit` | Props for the group component. |
| `indicator` | - | `ReactNodeOrFunction` | The tree indicator icon to use. |
| `indicatorProps` | - | `TreeIndicatorProps` | Props for the indicator component. |
| `label` | - | `ReactNode` | The label to display in the item. |
| `labelProps` | - | `TreeLabelProps` | Props for the label component. |
| `loadingScheme` | `"oval"` | `Loading.Scheme` | The loading scheme. |
| `onClose` | - | `() => void \| Promise` | Callback invoked to close the element. |
| `onOpen` | - | `() => void \| Promise` | Callback invoked to open the element. |
| `open` | - | `boolean` | If `true`, the element will be opened. |
| `query` | - | `string` | The query to search for in the tree item. |
| `rootProps` | - | `HTMLStyledProps<"li">` | Props for the root element. |
| `startElement` | - | `TreeItemReactNode` | The element to display at the start of the item. |
| `startElementProps` | - | `TreeStartElementProps` | Props for the start component. |
| `value` | - | `string` | The value of the item. |
## Accessibility
`Tree` follows the [WAI-ARIA - TreeView Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) for accessibility.
When `aria-label` is set, it will be read aloud by screen readers.
```tsx
```
### 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
| Element | Roles and Attributes | Usage |
| ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `ul.ui-tree__root` | `role="tree"` | Indicates that the element is a tree. |
| | `aria-multiselectable` | Set to `"true"` when `multiple={true}` or `checkable={true}`. |
| `li.ui-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 `span.ui-tree__label`. |
| `ul.ui-tree__group` | `role="group"` | Indicates that the element is a group. |
| | `aria-labelledby` | Sets the `id` of the related `span.ui-tree__label`. |
| | `aria-busy` | Set to `"true"` when the item's children are loading. |
| `input.ui-tree__checkbox` | `id` | Used to associate with the parent `input.ui-tree__checkbox`. |
| | `aria-controls` | Sets the `id` of related child `input.ui-tree__checkbox` elements. |
| | `aria-labelledby` | Sets the `id` of the related `span.ui-tree__label`. |
| `span.ui-tree__label` | `id` | Used to associate with `li.ui-tree__item`, `ul.ui-tree__group`, and `input.ui-tree__checkbox`. |
## Similar Components
- [DataList](https://yamada-ui.com/docs/components/data-list.md): `DataList` is used to display a list of data items.
- [List](https://yamada-ui.com/docs/components/list.md): `List` is a component for displaying lists. By default, it renders a `ul` element.
- [NativeAccordion](https://yamada-ui.com/docs/components/native-accordion.md): `NativeAccordion` is a component for a list that displays information in an expandable or collapsible manner using the HTML `details` element.
- [Accordion](https://yamada-ui.com/docs/components/accordion.md): `Accordion` is a component for a list that displays information in an expandable or collapsible manner.
- [Timeline](https://yamada-ui.com/docs/components/timeline.md): `Timeline` is a component that is used to display a list of events in chronological order.
- [Tabs](https://yamada-ui.com/docs/components/tabs.md): `Tabs` is a component for switching between different display areas.
- [NativeTable](https://yamada-ui.com/docs/components/native-table.md): `NativeTable` is a component for efficiently organizing and displaying data.
- [Sidebar](https://yamada-ui.com/docs/components/sidebar.md): `Sidebar` is a component used to display a list of items in a sidebar.
## Uses Components & Hooks
- [Checkbox](https://yamada-ui.com/docs/components/checkbox.md): `Checkbox` is a component used for allowing users to select multiple values from multiple options.
- [Icon](https://yamada-ui.com/docs/components/icon.md): `Icon` is a general icon component that can be used in your projects.
- [Collapse](https://yamada-ui.com/docs/components/collapse.md): `Collapse` is a component that allows you to expand or collapse an element for display.
- [Loading](https://yamada-ui.com/docs/components/loading.md): `Loading` is a component displayed during waiting times, such as when data is being loaded.
- [Motion](https://yamada-ui.com/docs/components/motion.md): `Motion` is a convenient component that extends the Yamada UI Style Props to `Motion`.
- [useDescendants](https://yamada-ui.com/docs/hooks/use-descendants.md): `useDescendants` is a custom hook that manages descendants.
- [useDisclosure](https://yamada-ui.com/docs/hooks/use-disclosure.md): `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](https://yamada-ui.com/docs/hooks/use-async-callback.md): `useAsyncCallback` is a custom hook for managing asynchronous callbacks.