---
name: cascade-select-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit CascadeSelect
for choosing a value from hierarchical data with Zag.js path values,
compound parts, parent or multiple selection, validation, and keyboard
navigation.
metadata:
component_version: "1.3.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/cascade-select"
contributor_sources: "libs/ui/src/molecules/cascade-select.tsx libs/ui/src/tokens/components/molecules/_cascade-select.css libs/ui/stories/molecules/cascade-select.stories.tsx"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit CascadeSelect Usage
Use CascadeSelect for form choices whose options have parent/child levels.
Use Select for a flat known list and TreeView for hierarchical navigation.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `CascadeSelect`.
**Use it when**
- A form value that lives inside a hierarchy: category → subcategory, region → city.
- Hierarchies deep or wide enough that one flat Select would be unreadable.
**Use something else when**
| Need | Use instead |
| --- | --- |
| A flat list of known options | Select |
| A flat list the user needs to search | Combobox |
| Navigating categories (links) | VerticalNavigation |
| Selecting nodes in a tree widget with arrow keys | TreeView |
**Do**
- Show the full path of the selected value in the trigger (`Clothing / Shirts / Linen`).
- Let users select parent levels only when a parent is a valid value; otherwise only leaves are selectable.
- Keep level labels short; order siblings meaningfully (alphabetical or by popularity), consistently.
**Don't**
- Use it for two levels with a handful of items — two Selects or a grouped Select read faster.
- Mix navigation links into a form control.
**Copy and states**
- Label is the noun of the final value (`Category`), placeholder `Select a category`.
- Path separator comes from the component; don't type `>` or `/`.
**Behaviour (from the UX spec)**
- Opening a branch is browsing, not choosing; closing without choosing keeps the previous value.
- Build the hierarchy from real parent/child data, never from sorted label prefixes. In `multiple` mode, same-named leaves stay distinguishable by their full paths.
- In RTL, set `dir` and let the kit order columns and indicators; don't mirror an LTR mock by hand.
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=xs` | legacy alias; use `sm` / `md` / `lg` |
| `state=readonly` | `readOnly` |
| item `type=branch` / `leaf` | item with / without `children` |
| content `depth=1…3` | not a prop; open columns rendered by `CascadeSelect.Node` |
| `cascadeselect-examples`, `cascadeselect-rtl` | reference frames (stories), not states |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/CascadeSelect → UX guidelines*.
## Setup
```tsx
const categories = [
{
label: "Electronics",
value: "electronics",
children: [{ label: "Phones", value: "phones" }],
},
]
CategoryChoose the most specific category.
```
Supported props:
```text
items: { label, value, children?, disabled? }[]
size: sm | md | lg (default md; legacy xs remains a compatibility alias)
validateStatus: default | error | success | warning
value/defaultValue: string[][]
highlightedValue/defaultHighlightedValue: string[]
multiple, allowParentSelection, closeOnSelect, highlightTrigger
disabled, required, readOnly, loopFocus
name, form, formatValue, onValueChange, onOpenChange, onHighlightChange
```
## Core Patterns
### Keep the compound anatomy intact
Use Label, Control, Trigger, ValueText, Positioner, Content, and Node. Node is
the default recursive renderer built from the public List, Item, ItemText,
ItemIndicator, and BranchIndicator parts. It renders separate columns with
numbered headers and a persistent marker on the expanded ancestor path.
Set `` to name the first column
(default: `Options`); subsequent headers use the expanded parent's label.
The marker means "this branch is open", not "this value is selected" — selected
values have a checkmark.
The trigger is a combobox with a tree popup. Arrow keys traverse levels,
Enter selects a value, and Escape closes the popup. On narrow screens the
columns scroll horizontally, and the active option scrolls into view as the
user traverses levels. Each visible child group
is labeled by its column header and owned by its expanded parent item.
### Treat each selected value as a complete path
A single selection still uses an array of paths. The Electronics → Phones
value is `[["electronics", "phones"]]`, not `["phones"]`.
Native `form.reset()` restores uncontrolled selections to `defaultValue` (or an
empty selection) and resolves the labels and submitted paths against the current
hierarchy. A removed default path stays empty instead of submitting stale values.
The `form` prop also supports controls outside the associated form. Cancelled
reset events leave the value unchanged; controlled values remain parent-owned.
A native reset does not emit `onValueChange`.
### Choose parent selection deliberately
Keep `allowParentSelection` false when only leaf choices are valid. Enable it
only when selecting a whole branch is meaningful.
### Associate guidance and validation with the trigger
`CascadeSelect.StatusText` generates a unique ID and automatically adds it to
the trigger's `aria-describedby` while mounted. You can provide a custom `id`;
existing `aria-describedby` references on `CascadeSelect.Trigger` are preserved.
Conditionally render StatusText when guidance or validation text is available;
unmounting it removes only its automatic description reference, leaving helper
text and caller-provided descriptions linked. Keep persistent helper text at
`status="default"` when the field becomes invalid, and render a separate
`` for an error inherited from root
`validateStatus="error"`. An explicit ``
also marks the trigger invalid, even when the root status is default. Every
mounted error ID joins `aria-errormessage`; changing its status or unmounting it
removes that error association. Helper and caller-owned IDs remain intact.
Put actionable correction text in the error rather than relying on border color.
The **Accessible status text** story demonstrates this with a product form:
saving an empty category reveals the error, selecting a leaf resolves it, and
saving again confirms success. The helper remains associated throughout.
Use `noValidate` on forms that present their own inline validation: keep
`required` on CascadeSelect for its accessible required state, validate the
selected path on submit, and show a linked error instead of relying on a native
validation bubble for the hidden form input.
### Let Select and popup tokens define appearance
CascadeSelect aliases its trigger tokens to Select and uses the shared popup
surface. Use component props or token overrides instead of duplicating its
padding, colors, radius, or item state styles with `className`.
## Common Mistakes
### HIGH Flat value shape
Wrong:
```tsx
```
Correct:
```tsx
import { useState } from "react"
import { CascadeSelect } from "@techsio/ui-kit/molecules/cascade-select"
function CategoryField() {
const [value, setValue] = useState([["electronics", "phones"]])
return setValue(value)}>
Product category
}
```
Source: https://zagjs.com/components/react/cascade-select
### HIGH Custom nested dropdown
Wrong:
```tsx
```
Correct (prop-only fragment; retain the labeled compound anatomy from Setup):
```tsx
{/* compound parts from Setup */}
```
Source: libs/ui/src/molecules/cascade-select.tsx
### HIGH Inline visual overrides
Wrong:
```tsx
```
Correct (prop-only fragment; retain the labeled compound anatomy from Setup):
```tsx
{/* compound parts from Setup */}
```
Source: libs/ui/src/tokens/components/molecules/_cascade-select.css
## Validation Commands
```sh
rg -n ']*(value|defaultValue)=\{\["' apps
rg -n ']*className=.*(border-|bg-|p[xy]?-|text-)' apps
rg -n '