Cascader
cascaderSelects a value through linked hierarchical option columns.
Usage
Basic usage
Click to expand step by step and select the leaf node to submit the entire path. When it is not controlled, use defaultValue to set the initial value.
<Cascader
nodes={nodes}
placeholder="Select region"
onChange={(path, nodePath) => setValue(path)}
/>hover Expand
expandTrigger="hover" will be expanded column by column when moved in. Click to submit.
<Cascader nodes={nodes} expandTrigger="hover" placeholder="Select Region" />Any layer optional
changeOnSelect allows you to select any level (not necessarily the leaf) and submit it.
<Cascader nodes={nodes} changeOnSelect placeholder="Select region" />Default vs. searchable
defaultValue echo path; showSearch A search box appears at the top of the floating layer and enter the direct link to the leaf.
<Cascader
nodes={nodes}
defaultValue={["zhejiang", "hangzhou", "xihu"]}
showSearch
/>Disabled
<Cascader nodes={nodes} disabled placeholder="Select region" />When to use
Use Cascader for hierarchical choices such as province/city/district, category/subcategory, or organizational levels, where the user drills down to select a complete path. Its value is an array of node key values from the root to the selected node. By default, only leaves can be selected; enable changeOnSelect to accept a node at any level. For a flat option list, use Combobox or Listbox instead.
Import
import { Cascader, flattenLeafPaths, filterLeafPaths, type CascaderLeafPath } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| nodes* | TreeNode[] | — | Hierarchical data using the shared tree-core TreeNode shape: key, label, children, and disabled. |
| value | string[] | — | Controlled key path from the root to the selected node. |
| defaultValue | string[] | [] | Initial key path when uncontrolled. |
| expandTrigger | "click" | "hover" | "click" | Interaction that expands the next level. |
| changeOnSelect | boolean | false | Whether a node at any level can be selected instead of leaves only. |
| showSearch | boolean | false | Shows a search field above the popup. Leaf paths are flattened for fuzzy matching, and selecting a result submits its full path. |
| searchPlaceholder | string | "\u641c\u7d22\u2026" | Search-field placeholder; the built-in Chinese copy means “Search…”. |
| placeholder | string | "\u8bf7\u9009\u62e9" | Trigger placeholder; the built-in Chinese copy means “Please select.” |
| disabled | boolean | — | Disables the component. |
| invalid | boolean | — | Applies invalid-state styling. |
| size | "sm" | "md" | "lg" | "md" | Trigger size. |
| className | string | — | Additional class name for the container. |
Events
| Event | Type | Description |
|---|---|---|
| onChange | (path: string[], nodes: TreeNode[]) => void | Called with the selected key path and its corresponding node chain. |
Usage guidelines
valueis a complete key-path array, such as["zhejiang","hangzhou","xihu"], not a single leaf key. Provide the full path when restoring a value so the expanded columns align correctly.- A
disablednode cannot be selected, and its subtree cannot be expanded through that node. - The second
onChangeargument is the selectedTreeNode[]chain. Use it to display labels instead of looking the nodes up again.
Related
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<Cascader
nodes={nodes}
expandTrigger="click"
value={value}
onChange={(path) => setValue(path)}
/>