A column-based cascading dropdown for picking a path through hierarchical data — regions, category trees, org charts. Each level opens the next column to its right; choosing a leaf commits the full path. The value is the array of option values from root to leaf. It is uncontrolled by default (defaultValue) or fully controlled via value + onChange. On small screens it switches from a popover to a bottom drawer automatically.

Installation

{
  "registries": {
    "@ikui": "https://ik-ui.pages.dev/r/{name}.json"
  }
}

pnpm dlx shadcn@latest add @ikui/cascader

Usage

import { Cascader, type CascaderOption } from "@/components/cascader";

const options: CascaderOption[] = [
  {
    value: "zhejiang",
    label: "Zhejiang",
    children: [{ value: "hangzhou", label: "Hangzhou" }],
  },
];

<Cascader
  options={options}
  onChange={(value, selected) => console.log(value, selected)}
/>;

Examples

Controlled value

Pass value and onChange to control the selection. onChange reports both the value path and the matching CascaderOption[].

Expand on hover

Set expandTrigger="hover" to open child columns on mouse-over instead of click. A leaf still requires a click to commit.

Disabled options

Mark any option disabled to make it (and its branch) unselectable. Here allowClear is also turned off, so there is no clear button.

Custom display

Use displayRender to control how the selected path renders in the trigger — here it shows only the leaf label instead of the full a / b / c path.

Props

CascaderOption