Cascader

Choose a value through a hierarchy of options.

Examples

A selection is committed at a leaf option. onChange supplies both the path and its options. Named fields submit a JSON array string. Use arrow keys to navigate levels, Enter to choose and Escape to close.

Live previewInteractive example

basic.tsx

import { Cascader } from '@sudden3/leaf-ui';

const options = [
  {
    value: 'design',
    label: 'Design',
    children: [
      { value: 'interface', label: 'Interface design' },
      { value: 'brand', label: 'Brand design' },
    ],
  },
  {
    value: 'engineering',
    label: 'Engineering',
    children: [
      { value: 'frontend', label: 'Frontend development' },
      { value: 'backend', label: 'Backend development' },
    ],
  },
  { value: 'archived', label: 'Archived category', disabled: true },
];

export function CascaderBasic() {
  return (
    <div className="leaf-demo-stack">
      <Cascader aria-label="Project category" options={options} placeholder="Choose a category" />
      <Cascader
        aria-label="Default category"
        options={options}
        defaultValue={['design', 'interface']}
      />
      <Cascader aria-label="Disabled category" options={options} disabled />
    </div>
  );
}

Live previewInteractive example

Selected path:zhejiang → hangzhou → xihu

controlled.tsx

import { Cascader } from '@sudden3/leaf-ui';
import { useState } from 'react';
import { regions } from './options';

export function CascaderControlled() {
  const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
  return (
    <div className="leaf-demo-stack">
      <Cascader aria-label="Delivery region" options={regions} value={value} onChange={setValue} />
      <span className="leaf-demo-note">Selected path:{value.join(' → ') || 'Not selected'}</span>
    </div>
  );
}

Cascader API

Property	Type	Default	Description
`options`	`readonly CascaderOption[]`	Required	Hierarchical options
`value` / `defaultValue`	`readonly string[]`	`[]`	Controlled path / initial uncontrolled path
`onChange`	`(value: string[], selectedOptions: CascaderOption[]) => void`	—	Runs when a leaf is selected or the path is cleared
`allowClear`	`boolean`	`true`	Clearing returns two empty arrays
`placeholder`	`string`	Locale default	Placeholder when empty; localized by ConfigProvider
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Control size
`status`	`'error' \| 'warning'`	—	Validation appearance
`disabled`	`boolean`	`false`	Disable the control
`name` / `form`	`string`	—	Field name / associated form ID
`required`	`boolean`	`false`	Require a selection
`onOpenChange`	`(open: boolean) => void`	—	Panel open-state changes
`ref`	`Ref<HTMLButtonElement>`	—	DOM reference

CascaderOption

Property	Type	Default	Description
`value`	`string`	Required	Value; unique at the same level
`label`	`string`	Required	Option label
`disabled`	`boolean`	`false`	Disable this option and its descendants
`children`	`readonly CascaderOption[]`	—	Child options; an option without children can be selected

Types

Import CascaderProps to describe component props. Option types in the API table link to their detailed fields above.

import type { CascaderProps, CascaderOption } from '@sudden3/leaf-ui';

Forms and localization

Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in FormField for labels, help and errors. ConfigProvider supplies regional themes and translated built-in UI. Application labels and options are your responsibility.

#Cascader

#Examples

#Cascader API

#CascaderOption