Examples
Choose a nested path
Each level narrows the next; selecting a leaf reports the full path to the feature.
Selected path: asia / vietnam / hanoi
Controlled Cascader path
import { Cascader, type CascaderOption } from "@phuctech/ui/components/cascader";
const regions: CascaderOption[] = [
{
value: "asia",
label: "Asia",
children: [
{ value: "vietnam", label: "Vietnam", children: [{ value: "hanoi", label: "Hanoi" }, { value: "hcmc", label: "Ho Chi Minh City" }] },
{ value: "japan", label: "Japan", children: [{ value: "tokyo", label: "Tokyo" }] },
],
},
{ value: "europe", label: "Europe", children: [{ value: "france", label: "France", children: [{ value: "paris", label: "Paris" }] }] },
];
export function Example() {
return <Cascader aria-label="Office location" options={regions} defaultValue={["asia", "vietnam", "hanoi"]} />;
}
Search across levels
A local search matches leaf labels and ancestor names without issuing a request.
Searchable hierarchy
import { Cascader, type CascaderOption } from "@phuctech/ui/components/cascader";
const categories: CascaderOption[] = [
{ value: "workspace", label: "Workspace", children: [{ value: "members", label: "Members" }, { value: "billing", label: "Billing" }] },
{ value: "account", label: "Account", children: [{ value: "profile", label: "Profile" }, { value: "security", label: "Security" }] },
];
export function Example() {
return <Cascader aria-label="Settings page" options={categories} searchPlaceholder="Search settings" />;
}
Disabled branch
A disabled ancestor also disables its descendants in both the columns and search results.
Hierarchy with a disabled branch
import { Cascader, type CascaderOption } from "@phuctech/ui/components/cascader";
const destinations: CascaderOption[] = [
{ value: "active", label: "Available locations", children: [{ value: "north", label: "North office" }] },
{ value: "closed", label: "Closed locations", disabled: true, children: [{ value: "archive", label: "Archived office" }] },
];
export function Example() {
return <Cascader aria-label="Office" options={destinations} placeholder="Choose an office" />;
}
When to use
Use Cascader when a user can narrow a location, category, or organizational path one level at a time. Use TreeSelect when the user needs to inspect several branches together or select multiple nodes.
Usage
import { Cascader, type CascaderOption } from "@phuctech/ui/components/cascader";
const regions: CascaderOption[] = [
{ value: "asia", label: "Asia", children: [{ value: "vietnam", label: "Vietnam" }] },
];
<Cascader aria-label="Region" options={regions} value={["asia", "vietnam"]} onValueChange={setPath} />Only leaf options commit as values. The callback receives the complete value path and selected leaf. The feature owns the path when value is supplied; otherwise defaultValue initializes local state.
Behavior
- Search is local to the supplied option tree and matches the full ancestor path. It does not call a service.
- A disabled option prevents interaction with its entire subtree, including results found by search.
- Escape closes the popup; Arrow Up/Down moves among the current level; Arrow Right opens a child level; Arrow Left returns to its parent; Home and End move to the first and last enabled option.
- Long option columns scroll within the popup. The horizontal level list can also scroll when the hierarchy has many levels.
API
Tokens
Accessibility
Give the trigger a visible form label or aria-label. The popup search has its own label. Use the arrow keys to inspect and move between levels, Enter or Space to activate an option, and Escape to close. Do not use placeholder text as the only label.
Do and don’t
Use a shallow hierarchy with labels that make each step easy to distinguish.
Use Cascader for a large tree that users need to browse or select in multiple branches.
Related
- TreeSelect keeps the hierarchy visible and supports multi-selection.
- Select handles a flat set of options.
- Field connects labels and validation feedback.