# TreeMultiSelect (/docs/tree-multi-select)
`TreeMultiSelect` lets the user pick **several** values from **hierarchical** data. It pairs a pills trigger (like [`MultiSelect`](/docs/multi-select)) with an always-expanded checkbox tree in a Popover: top-level rows sit flush, their descendants are connected by indent guide lines, and checking a folder cascades to everything inside it. A search field at the top of the popover filters the tree.
```tsx
import { TreeMultiSelect } from '@42-central/ui-react/tree-multi-select';
```
For a **single-value** tree picker, reach for [`TreeSelect`](/docs/tree-select).
## Playground [#playground]
## Data [#data]
`data` is a tree of nodes — each `{ value, label, disabled?, children? }`. A node with `children` is a **branch**: checking it toggles every leaf beneath it, and it reads as **indeterminate** when only some descendants are selected. A node without children is a **leaf**. `value` must be unique across the tree.
```tsx
const data = [
{ value: 'builtins', label: 'builtins', children: [
{ value: 'ft_cd', label: 'ft_cd' },
{ value: 'ft_echo', label: 'ft_echo' },
]},
{ value: 'parsing', label: 'parsing', children: [
{ value: 'lexer', label: 'lexer' },
]},
];
```
Each node also accepts an optional `testId`, for a stable `data-testid` on that node's own row
regardless of its label — see the [Testing](/docs/testing) guide. It defaults to
`` `item-${value}` `` when omitted.
## Controlled [#controlled]
`value` is the array of selected **leaf** values; `onChange` fires with the full selection on every toggle or pill removal. Branch state is derived, so the value never contains branch nodes.
```tsx
'use client';
import { useState } from 'react';
import { TreeMultiSelect } from '@42-central/ui-react/tree-multi-select';
export function FilePicker({ tree }) {
const [value, setValue] = useState([]);
return ;
}
```
## Selection [#selection]
Checking a folder selects everything inside it; partially-filled folders show an indeterminate state. Remove a value from its pill, or clear them all with `clearable`.
## Max lines [#max-lines]
`maxLines` caps the trigger's pills at N rows; any beyond collapse into a static **+N** counter. The hidden values stay selected — open the tree to deselect them.
## Start & end slots [#start--end-slots]
`startSlot` and `endSlot` place content at the trigger's inline-start / inline-end with the same slot layout as [`Input`](/docs/input). `endSlot` renders before the built-in clear button and chevron.
## Custom rendering [#custom-rendering]
Pass `renderItem` to fill each node's content yourself. It receives the `node` (`{ value, label, disabled?, children? }`) and its live `{ checked, indeterminate, leaf, disabled, depth }` state. `TreeMultiSelect` keeps the row — treeitem role, indent rails, roving focus, click, and the cascade — and the callback fills everything after the rails, **including the checkbox** (the default one is part of the content it replaces). Read `state.checked` / `state.indeterminate` to draw your own tri-state box. Define the function in a `"use client"` module so it survives the server → client boundary.
```tsx
'use client';
import { Check, Minus } from 'lucide-react';
const renderNode = (node, { checked, indeterminate }) => (
{checked && }
{indeterminate && }
{node.label}
);
```
### Typed payload [#typed-payload]
Nodes can carry an arbitrary, **typed** `payload` (`{ value, label, payload?, children? }`), read back as `node.payload` in `renderItem` — inferred from `data`, and `undefined` on nodes that omit it.
```tsx
'use client';
import type { TreeNodeData } from '@42-central/ui-react/tree-multi-select';
type FileMeta = { loc: number };
const tree: TreeNodeData[] = [
{ value: 'srcs', label: 'srcs', children: [
{ value: 'main.c', label: 'main.c', payload: { loc: 12 } },
]},
];
// node.payload is inferred as FileMeta | undefined
const renderNode = (node) => (
{node.label}
{node.payload && {node.payload.loc} LOC}
);
```
## Label, description & error [#label-description--error]
Built-in via [`Field`](/docs/field), like the rest of the family:
## API [#api]
## Accessibility [#accessibility]
* The tree is `role="tree"` with `aria-multiselectable`; each row is a `role="treeitem"` carrying `aria-checked` (`true` / `false` / `mixed`) and `aria-level`. The checkbox is presentational — selection state lives on the row.
* `↑` / `↓` move between rows, `Home` / `End` jump to the first / last, and `Space` / `Enter` toggle the focused node (cascading to its children). There is no expand / collapse — the tree is always fully shown.
* The trigger is a `role="combobox"` that opens the Popover; it traps focus and dismisses on outside-click / `Escape`. Label / description / error are associated via the built-in `Field`.
* When `searchable`, the popover opens with focus in the search field, and `↓` moves focus from the field into the first tree row.