build69
Sign inGet API key
build69  /  Components  /  Selection & Choice  /  Cascader

Cascader

v1.0.7NewUpdated 27 Aug 2026

Hierarchical dependent select (Ant Cascader-style) for tree-shaped choices such as Thai addresses (จังหวัด → เขต/อำเภอ → แขวง/ตำบล). Multi-column popover where each pick reveals the next level; the value is the string[]

View source← Back to catalog

Preview

Live · 15 stories
DefaultOpen ↗
▸Why this is recommendedcascaderselecthierarchydependent-select+5

The default, out-of-the-box Cascader.

Recommended for+14
  • ✓Thai address pickers (province → district → subdistrict)
  • ✓Product category selectors
  • ✓Org / department / cost-center pickers
  • ✓Any dependent drill-down taxonomy
Tags+6
cascaderselecthierarchydependent-selectaddresstreemulti-columnasyncdefault
Features+4
  • Multi-column popover, one column per level
  • Click or hover expansion (expandTrigger)
  • changeOnSelect commits intermediate levels
  • Search flattens the tree into full label paths
  • Async loadChildren with per-node spinner (isLeaf: false)
  • Custom displayRender for the joined trigger label
  • Clearable (✕ button; Backspace/Delete on closed trigger)
  • Controlled + uncontrolled value (string[] path)
  • Full keyboard: ↑↓ within a column, → expands, ← collapses, Enter selects, Esc closes
  • Trigger sizes sm / md / lg
  • i18n: labels prop overrides the built-in aria-label strings; placeholder / searchPlaceholder / emptyMessage stay overridable as props
Not recommended for−2
  • ✕Flat option lists (use Combobox / Select)
  • ✕Multi-select trees with checkboxes (use TreeView / TransferList)
  • ✕Very deep trees on narrow screens

Install

Ask your agent, or call the MCP tool directly. The resolved bundle is written into your project.

get_registry_item({ name: "Cascader" })

Usage

import { Cascader } from '@/components/inputs/cascader';

<Cascader
  options={thaiProvinces}
  value={address}
  onValueChange={setAddress}
  placeholder="จังหวัด / เขต / แขวง"
  clearable
/>

Tick variants in the left menu — each adds a tab with that variant’s real story source, the same code the preview above renders.

Props

PropTypeRequired
options

Root of the option tree ({ value, label, children?, disabled?, isLeaf? })

CascaderOption[]yes
value

Controlled path from root to the selected node

string[]—
defaultValue

Uncontrolled initial path

string[]—
onValueChange

Change callback with resolved option objects

(path: string[], selectedOptions: CascaderOption[]) => void—
expandTrigger

How branch columns expand (default click)

'click' | 'hover'—
changeOnSelect

Commit the value on every level click, not only leaves

boolean—
loadChildren

Async children fetch for isLeaf:false nodes (per-node spinner)

(option: CascaderOption, path: string[]) => Promise<CascaderOption[]>—
displayRender

Custom trigger label renderer

(labels: string[], selectedOptions: CascaderOption[]) => ReactNode—
clearable

Show a clear button when a value is set

boolean—
searchable

Path-flattening search input (default true)

boolean—
size

Trigger size

'sm' | 'md' | 'lg'—
labels

Override the built-in aria-label strings — clear affordance, search-results listbox, column {level} template (i18n). Merged over DEFAULT_CASCADER_LABELS.

Partial<CascaderLabels>—

Related

Platform docsAll componentsSource files