Tree

A tree component for displaying hierarchical data.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Tree } from '@base-ui/react/tree';

<Tree.Root>
  <Tree.Item>
    <Tree.ItemExpansionTrigger />
    <Tree.ItemGroupIndicator />
    <Tree.ItemLabel />
    <Tree.ItemLoadingIndicator />
    <Tree.ItemErrorIndicator />
  </Tree.Item>
  <Tree.CheckboxItem>
    <Tree.ItemExpansionTrigger />
    <Tree.CheckboxItemIndicator />
    <Tree.ItemGroupIndicator />
    <Tree.ItemLabel />
    <Tree.ItemLoadingIndicator />
    <Tree.ItemErrorIndicator />
  </Tree.CheckboxItem>
</Tree.Root>

For animated expand/collapse, wrap the item render function in Tree.AnimatedItemList:

Animated anatomy

<Tree.Root>
  <Tree.AnimatedItemList renderGroupTransition={<div />}>
    <Tree.Item>
      <Tree.ItemExpansionTrigger />
      <Tree.ItemLabel />
    </Tree.Item>
  </Tree.AnimatedItemList>
</Tree.Root>

Use selectionPropagation to automatically propagate selection changes through the tree hierarchy. When descendants is enabled, selecting a parent selects all its children. When parents is enabled, a parent becomes selected when all its children are selected. Toggle the checkboxes below to see how each option affects selection behavior.

Selection propagationparentsdescendants

Documents
Resume.pdf
Cover Letter.docx
Invoices
Photos
Music
Notes.txt

Checkbox items

<Tree.Item> uses replace selection: clicking an item selects it and deselects others (use Ctrl/Cmd to add, Shift to range-select).

<Tree.CheckboxItem> uses toggle selection: clicking an item toggles its selection without affecting others. It also renders checkbox ARIA semantics (aria-checked instead of aria-selected) and supports indeterminate state for parent items with partially selected children.

Documents
Resume.pdf
Cover Letter.docx
Invoices
Photos
Music
Notes.txt

Animated expand/collapse

Enable smooth height transitions when expanding and collapsing tree items using Tree.AnimatedItemList. Wrap your item render function inside this part and provide a renderGroupTransition element to control the animation wrapper. The wrapper exposes --tree-group-height, data-starting-style, and data-ending-style for CSS-based animations.

Documents
Resume.pdf
Cover Letter.docx
Invoices
Photos
Music
Notes.txt

Lazy loading

Load tree items on demand when a parent node is expanded. This is useful for large data sets where loading the entire tree upfront would be expensive.

Documents
Photos
Music
Notes.txt

API reference

Root

Groups all parts of the tree. Renders a <ul> element.

actionsRefRefObject<Tree.Root.Actions | null>—

Name: actionsRef
Description: A ref to imperative actions on the tree.
Type: React.RefObject<Tree.Root.Actions | null> | undefined

defaultExpandedItemsstring[][]

Name: defaultExpandedItems
Description: The items that are initially expanded.

To render a controlled tree, use the expandedItems prop instead.
Type: string[] | undefined
Default: []

defaultSelectedItemsUnion[]

Name: defaultSelectedItems
Description: The items that are initially selected.

To render a controlled tree, use the selectedItems prop instead.
Type: string[] | string | any | null | undefined
Default: []

disallowEmptySelectionbooleanfalse

Name: disallowEmptySelection
Description: Whether the tree disallows having no selected item. When true, at least one item must remain selected at all times.
Type: boolean | undefined
Default: false

expandOnClickbooleanfalse

Name: expandOnClick
Description: Whether clicking anywhere on an item row toggles expansion. When false, only Tree.ItemExpansionTrigger can expand items.
Type: boolean | undefined
Default: false

expandedItemsstring[]—

Name: expandedItems
Description: The expanded items.

To render an uncontrolled tree, use the defaultExpandedItems prop instead.
Type: string[] | undefined

getItemChildrenfunction(item) => item.children

Name: getItemChildren
Description: Used to determine the children of a given item.
Type: | ((item: Tree.Item.Model) => Tree.Item.Model[] | undefined) | undefined
Default: (item) => item.children

getItemIdfunction(item) => item.id

Name: getItemId
Description: Used to determine the id of a given item.
Type: ((item: Tree.Item.Model) => string) | undefined
Default: (item) => item.id

getItemLabelfunction(item) => item.label

Name: getItemLabel
Description: Used to determine the string label of a given item.
Type: ((item: Tree.Item.Model) => string) | undefined
Default: (item) => item.label

isItemDisabled((item: Tree.Item.Model) => boolean)() => false

Name: isItemDisabled
Description: Used to determine if a given item should be disabled.
Type: ((item: Tree.Item.Model) => boolean) | undefined
Default: () => false

isItemEditableUnionfalse

Name: isItemEditable
Description: Used to determine if a given item should be editable. If a boolean is provided, all items will be editable or non-editable.
Type: | boolean | ((item: Tree.Item.Model) => boolean) | undefined
Default: false

isItemSelectionDisabled((item: Tree.Item.Model) => boolean)() => false

Name: isItemSelectionDisabled
Description: Used to determine if a given item should have selection disabled.
Type: ((item: Tree.Item.Model) => boolean) | undefined
Default: () => false

itemFocusableWhenDisabledbooleanfalse

Name: itemFocusableWhenDisabled
Description: Whether disabled items should be focusable.
Type: boolean | undefined
Default: false

items^*Tree.Item.Model[]—

Name: items
Description: The items to render. Each item must have a unique identifier.
Type: Tree.Item.Model[]

lazyLoadingTreeLazyLoading—

Name: lazyLoading
Description: The lazy loading plugin instance, used to load items on demand when expanding a parent item.
Type: | { attach: attach onBeforeExpand: onBeforeExpand updateItemChildren: updateItemChildren destroy: destroy } | undefined

onExpandedItemsChangefunction—

Name: onExpandedItemsChange
Description: Event handler called when items are expanded or collapsed.
Type: | (( expandedItems: string[], eventDetails: Tree.Root.ExpansionChangeEventDetails, ) => void) | undefined

onItemClickfunction—

Name: onItemClick
Description: Event handler called when an item is clicked.
Type: | (( itemId: string, details: Tree.Item.ClickEventDetails, ) => void) | undefined

onItemExpansionTogglefunction—

Name: onItemExpansionToggle
Description: Event handler called when an item is expanded or collapsed.
Type: | (( itemId: string, isExpanded: boolean, details: Tree.Item.ExpansionToggleEventDetails, ) => void) | undefined

onItemFocusfunction—

Name: onItemFocus
Description: Event handler called when an item is focused.
Type: | (( itemId: string, details: Tree.Item.FocusEventDetails, ) => void) | undefined

onItemLabelChangefunction—

Name: onItemLabelChange
Description: Event handler called when the label of an item changes.
Type: | (( itemId: string, newLabel: string, details: Tree.ItemLabel.ChangeEventDetails, ) => void) | undefined

onItemSelectionTogglefunction—

Name: onItemSelectionToggle
Description: Event handler called when an item is selected or deselected.
Type: | (( itemId: string, isSelected: boolean, details: Tree.Item.SelectionToggleEventDetails, ) => void) | undefined

onSelectedItemsChangefunction—

Name: onSelectedItemsChange
Description: Event handler called when the selected items change.
Type: | (( selectedItems: string[] | string | any | null, eventDetails: Tree.Root.SelectionChangeEventDetails, ) => void) | undefined

selectedItemsUnion—

Name: selectedItems
Description: The selected items.

To render an uncontrolled tree, use the defaultSelectedItems prop instead.
Type: string[] | string | any | null | undefined

selectionModeTreeSelectionMode | undefined—

Name: selectionMode
Description: The selection mode of the tree. Use 'single' for single selection, 'multiple' for multiple selection.
Type: TreeSelectionMode | undefined

selectionPropagation{ parents?: boolean, descendants?: boolean }{ parents: false, descendants: false }

Name: selectionPropagation
Description: When selectionPropagation.descendants is set to true:

Selecting a parent selects all its descendants automatically.

Deselecting a parent deselects all its descendants automatically.

When selectionPropagation.parents is set to true:

Selecting all descendants of a parent selects the parent automatically.

Deselecting a descendant of a selected parent deselects the parent automatically.
Type: | { parents?: boolean; descendants?: boolean } | undefined
Default: { parents: false, descendants: false }

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

children^*((item: Tree.Item.Model) => ReactNode) | ReactNode—

Name: children
Description: The render function for each tree item, or a Tree.AnimatedItemList element for animated expand/collapse transitions.
Type: | ((item: Tree.Item.Model) => ReactNode) | React.ReactNode

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Tree.Root.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | ((state: Tree.Root.State) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.Root.State, ) => ReactElement)

data-disabled

Present when the tree is disabled.

data-tree

Present on the root element.

Attribute	Description	-
`data-disabled`	Present when the tree is disabled.
`data-tree`	Present on the root element.

AnimatedItemList

Renders tree items with animated expand/collapse transitions. Place inside Tree.Root instead of using a direct render function to opt into group transition animations.

renderGroupTransition^*Union—

Name: renderGroupTransition
Description: Customizes the wrapper element rendered during expand/collapse animation. Follows Base UI's render prop semantics.
Type: | React.ReactElement | (( props: HTMLAttributes<any> & RefAttributes<any>, state: TreeGroupTransitionState, ) => ReactElement)
Example: React element (props auto-merged via cloneElement):
renderGroupTransition={<div className={styles.GroupTransition} />}
Function (manual prop spreading):
renderGroupTransition={(props, state) => <div {...props} />}

children^*((item: Tree.Item.Model) => ReactNode)—

Name: children
Description: The render function for each tree item. Called with the item model for each visible item.
Type: (item: Tree.Item.Model) => ReactNode

Item

An individual tree item that uses replace selection behavior. Clicking selects the item and deselects others. Use modifier keys (Ctrl/Cmd, Shift) for multi-select operations. Renders a <li> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Tree.Item.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | ((state: Tree.Item.State) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.Item.State, ) => ReactElement)

data-selected

Present when the item is selected.

data-disabled

Present when the item is disabled.

data-collapsed

Present when the item is collapsed.

data-depth

The depth of the item in the tree hierarchy.

data-editing

Present when the item's label is being edited.

data-expandable

Present when the item has children and can be expanded.

data-expanded

Present when the item is expanded.

data-focused

Present when the item is focused.

data-item-id

The id of the item.

Attribute	Description	-
`data-selected`	Present when the item is selected.
`data-disabled`	Present when the item is disabled.
`data-collapsed`	Present when the item is collapsed.
`data-depth`	The depth of the item in the tree hierarchy.
`data-editing`	Present when the item's label is being edited.
`data-expandable`	Present when the item has children and can be expanded.
`data-expanded`	Present when the item is expanded.
`data-focused`	Present when the item is focused.
`data-item-id`	The id of the item.

CheckboxItem

A tree item that uses toggle selection behavior with checkbox semantics. Clicking toggles the item's selection without affecting other items. Renders a <li> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Tree.CheckboxItem.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.CheckboxItem.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.CheckboxItem.State, ) => ReactElement)

data-checked

Present when the item is checked.

data-unchecked

Present when the item is not checked.

data-disabled

Present when the item is disabled.

data-collapsed

Present when the item is collapsed.

data-depth

The depth of the item in the tree hierarchy.

data-editing

Present when the item's label is being edited.

data-expandable

Present when the item has children and can be expanded.

data-expanded

Present when the item is expanded.

data-focused

Present when the item is focused.

data-indeterminate

Present when the item is in an indeterminate state.

data-item-id

The id of the item.

Attribute	Description	-
`data-checked`	Present when the item is checked.
`data-unchecked`	Present when the item is not checked.
`data-disabled`	Present when the item is disabled.
`data-collapsed`	Present when the item is collapsed.
`data-depth`	The depth of the item in the tree hierarchy.
`data-editing`	Present when the item's label is being edited.
`data-expandable`	Present when the item has children and can be expanded.
`data-expanded`	Present when the item is expanded.
`data-focused`	Present when the item is focused.
`data-indeterminate`	Present when the item is in an indeterminate state.
`data-item-id`	The id of the item.

CheckboxItemIndicator

Indicates whether the checkbox item is checked. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Tree.CheckboxItemIndicator.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.CheckboxItemIndicator.State, ) => CSSProperties | undefined) | undefined

keepMountedbooleanfalse

Name: keepMounted
Description: Whether to keep the HTML element in the DOM when the checkbox item is not checked.
Type: boolean | undefined
Default: false

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.CheckboxItemIndicator.State, ) => ReactElement)

data-checked

Present when the checkbox item is checked.

data-unchecked

Present when the checkbox item is not checked.

data-disabled

Present when the checkbox item is disabled.

data-indeterminate

Present when the checkbox item is in an indeterminate state.

Attribute	Description	-
`data-checked`	Present when the checkbox item is checked.
`data-unchecked`	Present when the checkbox item is not checked.
`data-disabled`	Present when the checkbox item is disabled.
`data-indeterminate`	Present when the checkbox item is in an indeterminate state.

ItemLabel

Displays the label of a tree item. When the item is being edited, renders an <input> element; otherwise renders a <span>.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Tree.ItemLabel.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.ItemLabel.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.ItemLabel.State, ) => ReactElement)

data-editing

Present when the item's label is being edited.

Attribute	Description	-
`data-editing`	Present when the item's label is being edited.

ItemExpansionTrigger

A button that toggles the expansion state of a tree item. Renders a <button> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Tree.ItemExpansionTrigger.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.ItemExpansionTrigger.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.ItemExpansionTrigger.State, ) => ReactElement)

data-collapsed

Present when the item is collapsed.

data-expandable

Present when the item has children and can be expanded.

data-expanded

Present when the item is expanded.

Attribute	Description	-
`data-collapsed`	Present when the item is collapsed.
`data-expandable`	Present when the item has children and can be expanded.
`data-expanded`	Present when the item is expanded.

ItemGroupIndicator

A visual indicator for expandable tree items. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Tree.ItemGroupIndicator.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.ItemGroupIndicator.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.ItemGroupIndicator.State, ) => ReactElement)

data-collapsed

Present when the item is collapsed.

data-expandable

Present when the item has children and can be expanded.

data-expanded

Present when the item is expanded.

Attribute	Description	-
`data-collapsed`	Present when the item is collapsed.
`data-expandable`	Present when the item has children and can be expanded.
`data-expanded`	Present when the item is expanded.

ItemLoadingIndicator

Displays a loading indicator for a tree item that is lazily loading its children. Only renders when the item is in a loading state. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Tree.ItemLoadingIndicator.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.ItemLoadingIndicator.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.ItemLoadingIndicator.State, ) => ReactElement)

data-loading

Present when the item is loading.

Attribute	Description	-
`data-loading`	Present when the item is loading.

ItemErrorIndicator

Displays an error indicator for a tree item that failed to load its children. Only renders when the item is in an error state. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Tree.ItemErrorIndicator.State, ) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Tree.ItemErrorIndicator.State, ) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tree.ItemErrorIndicator.State, ) => ReactElement)

data-error

Present when the item has an error.

Attribute	Description	-
`data-error`	Present when the item has an error.