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