Tree Select

Demo & usage

More examples

When to use

• Picking one node out of a hierarchy the user already thinks of as a tree — folders, org units, categories.
• A taxonomy too deep for a flat select but too shallow to need a full page.
• For a strictly level-by-level walk (country → state → city), the Cascader reads better; for browsing rather than picking, use the Tree View.

Async states

• loading
• empty
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `options`, `loading` and `error`.
• `debounceMs` (default 300) collapses a burst of typing into one request. Set it to 0 only when the query is driven by clicks.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Single or multiple selection.
• Leaf-only or any-node selection.
• Filter box, local or server-side, with a configurable debounce.
• Three trigger sizes, clearable, disabled.

Best practices

• Do: Leave `selectable` at `leaf` for a taxonomy, and switch to `any` for a folder picker where every level is a valid answer.
• Do: Bind `[(expandedValues)]` when the tree reloads — otherwise the user re-opens the same branches after every refresh.
• Do: Turn `localFilter` off when you answer `(search)` from the server; filtering locally as well would hide rows the server had just decided were matches.
• Don't: Do not put thousands of nodes behind it unfiltered — this panel renders every visible row, so use server-side search for a large tree.
• Tip: The panel is portalled to `<body>`, so it escapes `overflow: hidden` and transformed ancestors and is destroyed on close.
• Do: Expect tri-state ancestry in `multiple` mode: ticking a branch takes its enabled contents with it, and a branch completes once every child the user could tick is ticked. This control used to tick one node and nothing else, so somebody who ticked "Documents" and pressed Save sent one value where they plainly meant the contents.
• Don't: Don't expect a tick to reach a `disabled` descendant. It cannot, in either direction — a read-only row the user could not have selected must not arrive in your change event because its parent was ticked, and a parent tick must not clear one either.
• Do: Use `checkedLeafValues()` when your API wants only leaves. `checkedValues` keeps the branch ids because they are the complete answer to "what is selected" — and because dropping them loses the difference between "the whole folder" and "every file in it, which happens to be all of them", two statements that diverge the moment a file is added.
• Don't: Don't read the mixed state as a value. `aria-checked="mixed"` and the dash are presentation; `checkedValues` holds strings and there is no third thing to store — the same contract Checkbox documents.
• Do: Use `loadChildren` for a tree you cannot fetch whole. This component had `loading` and `error` inputs and NO loader — a host could say "something is loading" and could say "it failed", and had no way to make anything load, so the only shape it supported was fetching the whole tree up front.
• Do: Honour the `AbortSignal` your loader is handed. Collapsing a branch cancels its request: a user who opens a folder, gets bored and collapses it has said they no longer want it, and without cancellation the response still lands and grafts children into a branch that is not on screen.
• Don't: Don't expect a failed branch to be a dead end. It is marked (`branchFailed`) and retried when the user expands it again — a failure with no way back but a page reload is worse than the failure.

Accessibility

• The trigger is a `button` with `aria-haspopup="tree"`, `aria-expanded` and `aria-controls`; the panel is a `role="tree"` with `aria-multiselectable` in multi mode.
• Every row is a `role="treeitem"` carrying `aria-level`, `aria-posinset`, `aria-setsize`, `aria-selected` and — only where it can open — `aria-expanded`.
• Keyboard: ↑/↓ move, →/← expand, collapse or jump to the parent, Enter/Space select, Escape closes. DOM focus stays in the filter box and the active row is published through `aria-activedescendant`.