Cascader

A regular hierarchy picked one level at a time, in side-by-side columns — so the path stays readable and the siblings you passed are still visible.

src/components/ui/cascader.tsx

About

From the component's own source, where it was written.

A hierarchy picked one level at a time, in side-by-side columns.

**Columns, not a nested tree.** For a hierarchy that is genuinely a classification — country → region → city, category → subcategory → type — columns show you where you are and what the siblings were, which a tree of disclosure triangles hides as soon as it scrolls. Each column is one decision, so the path is readable back out of the control.

**Use Tree instead when the shape is uneven**, when a user needs several branches open at once, or when depth varies wildly. This is for regular hierarchies of two to four levels.

changeOnSelect is the difference between "pick a city" and "pick anywhere, at any level" — with it on, choosing a region is a valid answer and does not force a descent to a leaf.

Install

npx astralyx-ui add cascader

Usage

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

<Cascader options={regions} value={path} onChange={setPath} />

Composer

Change the props and the source below follows.

Props

changeOnSelect

tsx

<Cascader
  options={regions}
  value={path}
  onChange={setPath}
  changeOnSelect={false}
/>

Examples

Region, country, city

tsx

<Cascader options={regions} value={path} onChange={setPath} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`Cascader`

Extends Omit<ComponentProps<'div'>, 'onChange' | 'defaultValue'>.

Prop	Type	Default	Description
options	CascaderOption[]	required	The value is the path from the root: `['eu', 'de', 'ber']`.
value	string[]	—	The value is the path from the root: `['eu', 'de', 'ber']`.
defaultValue	string[]	[]	—
onChange	(path: string[], options: CascaderOption[]) => void	—	—
placeholder	string	'Select…'	—
changeOnSelect	boolean	false	The difference between "pick a city" and "pick anywhere, at any level".
separator	string	' / '	Joins the path for display.
size	'sm' \| 'md' \| 'lg'	'md'	—
expandOnHover	boolean	true	Browsing opens the next column without committing anything.
disabled	boolean	—	—
invalid	boolean	—	—
label	string	—	—
emptyLabel	string	'Nothing here.'	—

Types

`CascaderOption`

A hierarchy picked one level at a time, in side-by-side columns.

Field	Type	Description
value	string	—
label	ReactNode	—
children?	CascaderOption[]	—
disabled?	boolean	—

Behaviour

Topic	Detail	Description
columns	not a tree	For a real classification, columns show where you are and what the siblings were — which a tree of disclosure triangles hides as soon as it scrolls.
vs Tree	when to switch	Use `Tree` when the shape is uneven, when several branches must be open at once, or when depth varies wildly. This is for regular hierarchies two to four levels deep.