Cascader

Demo & usage

More examples

When to use

• Selecting from naturally hierarchical data: location, category trees, org units.
• You want one compact control instead of several dependent dropdowns.
• For a flat list use Select Dropdown; for browsing a big tree use Tree View.

Async states

• error
• retry

Outputs

Customization & theming

• Feed `options` as a `CascaderNode[]` tree; the path is emitted as an array of values via `[(value)]`.
• Set `expandTrigger` to `hover` or `click`, and allow partial paths with `changeOnSelect`.
• Enable `searchable` for flat path search, tune `separator` for the displayed label, and pick a `size` (sm, md, lg).
• Provide `loadData` to lazily fetch children on expand — mark branch nodes with `isLeaf: false` and no `children`; a spinner shows while loading.
• Turn on `multiple` for multi-select: leaves render checkboxes, the panel stays open, and picks surface as removable chips. Bind `[(checkedValues)]` (a `string[][]` of value paths) and listen to `valuesChange` / `selectionsChange`.
• Toggle the clear affordance with `clearable` (defaults to on) — it clears the single value or every checked chip.
• Implements `ControlValueAccessor`, so single-select also binds with `[formControl]` / `[(ngModel)]` and respects `control.disable()` — `[(value)]` still works for non-form usage.
• Responsive: the body-portaled panel caps its width and height to the viewport and the column strip scrolls horizontally, so a multi-column cascader never runs off-screen on a phone or tablet.

Best practices

• Do: Keep the hierarchy to 2–4 levels so the path stays readable in the trigger.
• Do: Enable `searchable` when any level has many nodes.
• Tip: Use `changeOnSelect` only when intermediate (non-leaf) selections are valid.
• Do: Handle a saved path whose middle node has gone. It used to render as a SHORTER, complete-looking path — `[eu, uk, lon]` with the UK branch removed read simply as "Europe", which is a selection somebody could plausibly have made — while the form still held the three-level value. It now reads `Europe / 2 unavailable`, and `hasStalePath()` / `unresolvedDepth()` / `stalePathValues()` let you react.
• Don't: Don't assume a short path is a broken one. Selecting a non-leaf node is legitimate here: "Europe" chosen on purpose must look exactly like "Europe" chosen on purpose, and different from "Europe" as the wreck of a deeper path. That is what the unavailable count distinguishes.
• Do: Stamp submissions with a schema version and migrate them on load. A v1 submission opened under v2 was undefined in three ways: renamed fields were SILENTLY DROPPED on the next save (`svPruneHidden` cannot tell "not in the schema" from "hidden"), surviving values kept their old TYPE until somebody touched the field, and nothing recorded which schema produced the submission. `svMigrateValue` runs your steps and reports what is left over.
• Do: Call `svOrphanedKeys(schema, value)` before you save. It is what turns a rename from silent data loss into a reported condition — you get `["name", "dept"]` and can migrate, warn, or refuse, rather than discovering months later that a column emptied.
• Don't: Don't write one "upgrade from anything" function. `SvSchemaMigration` steps go from `to - 1` to `to`, because a submission can be three versions behind and a function handling every origin grows a branch per release and is tested for none of them. A missing step STOPS the chain and sets `incomplete` — running v3's migration on a v1 value usually "succeeds" and quietly produces nonsense.
• Do: Take the optional second argument in `loadData` — an `AbortSignal` — and honour it. A branch the user has navigated away from is now cancelled; before, the request kept running and its response was inserted into a column that was no longer on screen. On a deep tree browsed quickly that was dozens of live requests.

Accessibility

• The trigger exposes `aria-expanded`/`aria-haspopup` and is named via `ariaLabel` (announced with the selected path); each column is a `role="listbox"` of `role="option"` rows with `aria-selected`.
• The popover is a non-modal `role="dialog"`; the search box is labelled; arrows move within a level and Esc closes.
• In multi-select mode each leaf row reflects its checked state via `aria-selected`, and every chip has a labelled "Remove <item>" control operable with Enter/Space.
• Closes on outside click and restores focus to the trigger; all panel ids are generated per instance.