Tree Select

ProNew

A select whose options are a tree, with search that opens the matching branches, single or multiple choice and a combobox popup that follows the ARIA pattern.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it for a form field that picks a node from a hierarchy: a category, region, team or folder.

Do not use it for a short flat list (use a select) or when people must see the whole tree at once (use tree-view).

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tree-select

It uses popover, input, tree-view, checkbox-tree, filterable-tree, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The options.
`value / defaultValue / onValueChange`	`string[]`	`[]`	Selected ids. One at most unless `multiple`.
`multiple`	`boolean`	`false`	Use checkboxes; a branch selects its leaves.
`selectable`	`"any" \| "leaf"`	`"any"`	Single mode: whether a branch can be chosen.
`placeholder / searchPlaceholder / emptyText`	`string`	-	Texts.
`defaultExpanded`	`string[]`	`[]`	Branches open before a search.
`aria-label / aria-labelledby`	`string`	-	Names the button.
`aria-describedby / aria-invalid / aria-required`	-	-	Helper text, error state and required state from a form field.

Accessibility

The button has role combobox, aria-haspopup="tree", aria-expanded and aria-controls.
The result count is announced as you type.
With selectable="leaf" a branch only opens and closes.
The selected value is shown as its path (Europe / France).

Keyboard

ArrowDown on the closed button: open the popup. Enter / Space: toggle it.
In the search field: type to filter, ArrowDown moves into the tree, Escape closes.
In the tree: the tree keys from tree-view; Enter or Space chooses (single) or checks (multiple).
In single mode a choice closes the popup and returns focus to the button.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (tree-select.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it for a form field that picks a node from a hierarchy: a category, region, team or folder.

Do not use it for a short flat list (use a select) or when people must see the whole tree at once (use tree-view).

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tree-select

It uses popover, input, tree-view, checkbox-tree, filterable-tree, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The options.
`value / defaultValue / onValueChange`	`string[]`	`[]`	Selected ids. One at most unless `multiple`.
`multiple`	`boolean`	`false`	Use checkboxes; a branch selects its leaves.
`selectable`	`"any" \| "leaf"`	`"any"`	Single mode: whether a branch can be chosen.
`placeholder / searchPlaceholder / emptyText`	`string`	-	Texts.
`defaultExpanded`	`string[]`	`[]`	Branches open before a search.
`aria-label / aria-labelledby`	`string`	-	Names the button.
`aria-describedby / aria-invalid / aria-required`	-	-	Helper text, error state and required state from a form field.

Accessibility

The button has role combobox, aria-haspopup="tree", aria-expanded and aria-controls.
The result count is announced as you type.
With selectable="leaf" a branch only opens and closes.
The selected value is shown as its path (Europe / France).

Keyboard

ArrowDown on the closed button: open the popup. Enter / Space: toggle it.
In the search field: type to filter, ArrowDown moves into the tree, Escape closes.
In the tree: the tree keys from tree-view; Enter or Space chooses (single) or checks (multiple).
In single mode a choice closes the popup and returns focus to the button.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (tree-select.test.tsx) that covers its keyboard paths, roles and states.