Cascader

Forms

Selection

Hierarchical cascading selection with multi-level navigation, search, and flexible interaction modes. Ideal for selecting from deeply nested category structures.

Preview

Click to navigate through hierarchical options

Location

Selected: None

Variants

Different input styles

Default

Filled

With Default Selection

Pre-selected hierarchical path

Default Location

Hover Trigger

Expand menus on hover instead of click

Hover Cascader

Change on Select

Allow selection of intermediate levels, not just leaf nodes

Product Category

Selected: None

Searchable Cascader

Search across all levels of the hierarchy

Search Location

Custom Path Separator

Use custom separator for path display

Custom Separator

Sizes

Different input sizes

Small

Medium

Large

Error State

Validation error display

Location

Please select a location

Props

Cascader component API reference

Prop	Type	Default	Description
`options`	`CascaderOption[]`	`[]`	Hierarchical options
`value`	`string[]`	`[]`	Selected value path
`onChange`	`(value: string[], options: CascaderOption[]) => void`	—	Callback when value changes
`placeholder`	`string`	`'Select...'`	Placeholder text
`expandTrigger`	`'click' \| 'hover'`	`'click'`	How to expand menus
`changeOnSelect`	`boolean`	`false`	Allow selecting intermediate levels
`showPath`	`boolean`	`true`	Show full path in input
`separator`	`string`	`' / '`	Path separator character
`searchable`	`boolean`	`false`	Enable search functionality
`disabled`	`boolean`	`false`	Disable the cascader
`variant`	`'default' \| 'filled' \| 'error'`	`'default'`	Input style variant
`inputSize`	`'sm' \| 'md' \| 'lg'`	`'md'`	Input size
`label`	`string`	—	Label text
`error`	`string`	—	Error message
`helperText`	`string`	—	Helper text below input

CascaderOption Type

Prop	Type	Default	Description
`value*`	`string`	—	Option value
`label*`	`string`	—	Display label
`children`	`CascaderOption[]`	—	Child options
`disabled`	`boolean`	—	Disable this option

Usage

Import and implementation example

import { Cascader, CascaderOption } from '@/components/ui/cascader'

const options: CascaderOption[] = [
  {
    value: 'usa',
    label: 'United States',
    children: [
      {
        value: 'california',
        label: 'California',
        children: [
          { value: 'sf', label: 'San Francisco' },
          { value: 'la', label: 'Los Angeles' },
        ],
      },
    ],
  },
]

export default function Example() {
  const [value, setValue] = useState<string[]>([])

  return (
    <Cascader
      options={options}
      value={value}
      onChange={(val, opts) => {
        setValue(val)
        console.log('Selected options:', opts)
      }}
      placeholder="Select location"
      label="Location"
      expandTrigger="click"
      changeOnSelect={false}
      searchable={true}
    />
  )
}

This block is self-contained (no UI component dependencies)

Features

Built-in functionality

Multi-level navigation: Navigate through deeply nested hierarchies
Click or hover trigger: Choose interaction mode for menu expansion
Intermediate selection: Option to select non-leaf nodes
Full-text search: Search across all levels of the hierarchy
Path display: Show full path or just the final selection
Custom separators: Customize path separator character
Clear button: One-click to clear selection
Keyboard navigation: Full keyboard support for accessibility
Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

Trigger button has proper focus managementOptions are keyboard navigableSearch input has label association

Keyboard Navigation

Key	Action
`Tab`	Focus the trigger button
`Enter / Space`	Open dropdown or select option
`Escape`	Close the dropdown
`Arrow keys`	Navigate between options

Notes

Selected path shown in input as readable text
Options highlight on hover/focus
Chevron indicates expandable options
Disabled options are visually distinct

Related Components

Select Combobox Searchable Select Tree