Cascader

Form

Input

Select

A multi-level dropdown selector for hierarchical data, with search, keyboard navigation, and path display.

Preview

Select from a hierarchical menu

Location

Variants

Default and filled visual styles

Default Variant

Filled Variant

Searchable

Enable search to find options across all levels

Searchable Cascader

Props

Component API reference

Prop	Type	Default	Description
`options`	`CascaderOption[]`	`[]`	Hierarchical options with value, label, and optional children
`value`	`string[]`	`[]`	Selected value path as array of values
`onChange`	`(value: string[], selectedOptions: CascaderOption[]) => void`	—	Callback when selection changes
`placeholder`	`string`	`'Select...'`	Placeholder text when no value selected
`expandTrigger`	`'click' \| 'hover'`	`'click'`	How to expand child menus
`changeOnSelect`	`boolean`	`false`	Allow selecting non-leaf nodes
`showPath`	`boolean`	`true`	Show full path in the trigger
`separator`	`string`	`' / '`	Path separator character
`searchable`	`boolean`	`false`	Enable search input in dropdown
`multiple`	`boolean`	`false`	Allow multiple selections
`disabled`	`boolean`	`false`	Disable the cascader
`variant`	`'default' \| 'filled' \| 'error'`	`'default'`	Visual variant
`inputSize`	`'sm' \| 'md' \| 'lg'`	`'md'`	Trigger button size
`label`	`string`	—	Label text above the cascader
`error`	`string`	—	Error message (switches to error variant)
`helperText`	`string`	—	Helper text below the cascader
`className`	`string`	—	Additional CSS classes

Usage

Import and implementation example

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

const options: CascaderOption[] = [
  {
    value: 'us',
    label: 'United States',
    children: [
      {
        value: 'ca',
        label: 'California',
        children: [
          { value: 'sf', label: 'San Francisco' },
        ],
      },
    ],
  },
]

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

  return (
    <Cascader
      options={options}
      value={value}
      onChange={(val, opts) => setValue(val)}
      label="Location"
      searchable
    />
  )
}

Features

Built-in functionality

Multi-level menus: Nested panel display for hierarchical data
Path display: Shows selected path with configurable separator
Search: Search across all levels with flattened results
Click or hover expand: Configurable trigger for expanding child menus
Clear selection: X button to clear the current selection
Three variants: Default, filled, and error visual styles
Three sizes: Small, medium, and large trigger sizes
Error and helper text: Built-in validation display
Disabled options: Individual options can be disabled

Accessibility

Accessibility considerations

ARIA Attributes

Trigger button is focusable and keyboard accessibleFocus ring wraps the trigger when open

Keyboard Navigation

Key	Action
`Enter / Space`	Open/close dropdown, select an option
`Escape`	Close dropdown (via click outside)

Notes

Dropdown closes when clicking outside the component
Active option is highlighted with distinct background
Chevron indicators show which options have children
Search input auto-focuses when searchable dropdown opens

Related Components

Select TreeView Dropdown