Skip to content

Design system

Documentation

DesignComponents / Cascader

Components / Cascader

Beta

Cascader

Choose a leaf from a hierarchy when each selection determines the options at the next level.

On this page

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

Disabled branch

A disabled ancestor also disables its descendants in both the columns and search results.

Hierarchy with a disabled branch

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

Component API
PropTypeDefaultDescriptionConstraints
optionsreadonly CascaderOption[]requiredHierarchical options with value, label, disabled, and optional children.Sibling values must be unique; provide stable string values and readable labels.
value / defaultValuereadonly string[] | nulluncontrolled empty pathSelected path from the root to one leaf.Supply value with onValueChange for controlled use. Only leaf options can be selected through interaction.
onValueChange(path: string[], option?: CascaderOption) => void—Receives the committed leaf path; clearing reports an empty path.The parent owns the selected value when value is controlled.
placeholder / searchPlaceholder / searchLabel / emptyMessagestring / string / string / ReactNodeChoose an option / Search options / Search options / No options found.Trigger, search, and empty-result copy.The trigger and search input each keep an accessible name.
disabled / aria-invalid / className / refbutton propsfalse / — / — / —Forwards trigger state, styling, native button attributes, and ref.Pair invalid state with visible feature-owned help or error text.

Tokens

Component tokens
TokenRoleEffective valueUsage
--size-control-md / --radius-mdTriggerShared Button control scaleAligns Cascader with Select and form controls.
--color-bg-elevated / --elevation-popoverPopup surfaceSemantic rolesKeeps the portaled option surface consistent with Popover.
--focus-ring-*Keyboard focusShared focus ringMakes level and search navigation visible.

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

Do

Use a shallow hierarchy with labels that make each step easy to distinguish.

Don’t

Use Cascader for a large tree that users need to browse or select in multiple branches.

  • TreeSelect keeps the hierarchy visible and supports multi-selection.
  • Select handles a flat set of options.
  • Field connects labels and validation feedback.