2016-07-21 10:09:01 +08:00
---
category: Components
2022-11-09 12:28:04 +08:00
group: Data Entry
2016-07-21 10:09:01 +08:00
title: Cascader
2024-03-22 14:22:42 +08:00
description: Cascade selection box.
2024-01-29 14:50:36 +08:00
cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*ngTnQZNOcK0AAAAAAAAAAAAADrJ8AQ/original
coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*Nt8xR7afyr0AAAAAAAAAAAAADrJ8AQ/original
2022-11-09 12:28:04 +08:00
demo:
cols: 2
2016-07-21 10:09:01 +08:00
---
2016-09-10 13:43:30 +08:00
## When To Use
2016-07-21 10:09:01 +08:00
- When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.
- When selecting from a large data set, with multi-stage classification separated for easy selection.
2016-11-29 17:13:24 +08:00
- Chooses cascade items in one float layer for better user experience.
2016-07-21 10:09:01 +08:00
2022-11-09 12:28:04 +08:00
## Examples
2022-11-17 17:31:26 +08:00
<!-- prettier - ignore -->
2022-11-09 12:28:04 +08:00
< code src = "./demo/basic.tsx" > Basic< / code >
< code src = "./demo/default-value.tsx" > Default value< / code >
< code src = "./demo/custom-trigger.tsx" > Custom trigger< / code >
< code src = "./demo/hover.tsx" > Hover< / code >
< code src = "./demo/disabled-option.tsx" > Disabled option< / code >
< code src = "./demo/change-on-select.tsx" > Change on select< / code >
< code src = "./demo/multiple.tsx" > Multiple< / code >
< code src = "./demo/showCheckedStrategy.tsx" > ShowCheckedStrategy< / code >
< code src = "./demo/size.tsx" > Size< / code >
< code src = "./demo/custom-render.tsx" > Custom render< / code >
< code src = "./demo/search.tsx" > Search< / code >
< code src = "./demo/lazy.tsx" > Load Options Lazily< / code >
< code src = "./demo/fields-name.tsx" > Custom Field Names< / code >
< code src = "./demo/suffix.tsx" debug > Custom Icons< / code >
< code src = "./demo/custom-dropdown.tsx" > Custom dropdown< / code >
< code src = "./demo/placement.tsx" > Placement< / code >
< code src = "./demo/status.tsx" > Status< / code >
2023-09-26 17:34:49 +08:00
< code src = "./demo/panel.tsx" version = ">= 5.10.0" > Panel< / code >
2022-11-09 12:28:04 +08:00
< code src = "./demo/render-panel.tsx" debug > _InternalPanelDoNotUseOrYouWillBeFired< / code >
2016-07-21 10:09:01 +08:00
## API
2023-08-08 18:27:48 +08:00
Common props ref: [Common props](/docs/react/common-props)
2019-07-09 19:10:36 +08:00
```jsx
< Cascader options = {options} onChange = {onChange} / >
2016-07-21 10:09:01 +08:00
```
2019-07-11 14:14:33 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
2023-08-15 15:12:45 +08:00
| allowClear | Show clear button | boolean \| { clearIcon?: ReactNode } | true | 5.8.0: Support object type |
2023-08-09 11:57:01 +08:00
| autoClearSearchValue | Whether the current search will be cleared on selecting an item. Only applies when `multiple` is `true` | boolean | true | 5.9.0 |
2020-06-30 16:36:58 +08:00
| autoFocus | If get focus when component mounted | boolean | false | |
2021-11-17 11:06:30 +08:00
| changeOnSelect | (Work on single select) Change value on each selection if set to true, see above demo for details | boolean | false | |
2020-06-30 16:36:58 +08:00
| className | The additional css class | string | - | |
| defaultValue | Initial selected value | string\[] \| number\[] | \[] | |
| disabled | Whether disabled select | boolean | false | |
2022-02-18 15:02:26 +08:00
| displayRender | The render function of displaying selected options | (label, selectedOptions) => ReactNode | label => label.join(`/`) | `multiple` : 4.18.0 |
2023-05-12 17:46:13 +08:00
| tagRender | Custom render function for tags in `multiple` mode | (label: string, onClose: function, value: string) => ReactNode | - | |
2022-08-05 11:21:07 +08:00
| popupClassName | The additional className of popup overlay | string | - | 4.23.0 |
2020-10-21 10:33:43 +08:00
| dropdownRender | Customize dropdown content | (menus: ReactNode) => ReactNode | - | 4.4.0 |
2020-06-30 16:36:58 +08:00
| expandIcon | Customize the current item expand icon | ReactNode | - | 4.4.0 |
2020-10-21 10:33:43 +08:00
| expandTrigger | expand current item when click or hover, one of `click` `hover` | string | `click` | |
2020-06-30 16:36:58 +08:00
| fieldNames | Custom field name for label and value and children | object | { label: `label` , value: `value` , children: `children` } | |
| getPopupContainer | Parent Node which the selector should be rendered to. Default to `body` . When position issues happen, try to modify it into scrollable content and position it relative. [example ](https://codepen.io/afc163/pen/zEjNOy?editors=0010 ) | function(triggerNode) | () => document.body | |
| loadData | To load option lazily, and it cannot work with `showSearch` | (selectedOptions) => void | - | |
2021-09-27 18:16:50 +08:00
| maxTagCount | Max tag count to show. `responsive` will cost render performance | number \| `responsive` | - | 4.17.0 |
| maxTagPlaceholder | Placeholder for not showing tags | ReactNode \| function(omittedValues) | - | 4.17.0 |
2023-02-16 19:20:23 +08:00
| maxTagTextLength | Max tag text length to show | number | - | 4.17.0 |
2020-06-30 16:36:58 +08:00
| notFoundContent | Specify content to show when no result matches | string | `Not Found` | |
2021-08-31 15:51:02 +08:00
| open | Set visible of cascader popup | boolean | - | 4.17.0 |
2022-12-22 14:12:26 +08:00
| options | The data options of cascade | [Option ](#option )\[] | - | |
2020-06-30 16:36:58 +08:00
| placeholder | The input placeholder | string | `Please select` | |
2022-01-20 16:54:47 +08:00
| placement | Use preset popup align config from builtinPlacements | `bottomLeft` `bottomRight` `topLeft` `topRight` | `bottomLeft` | 4.17.0 |
2022-12-22 14:12:26 +08:00
| showSearch | Whether show search input in single mode | boolean \| [Object ](#showsearch ) | false | |
2020-06-30 16:36:58 +08:00
| size | The input size | `large` \| `middle` \| `small` | - | |
2022-02-17 15:08:13 +08:00
| status | Set validation status | 'error' \| 'warning' | - | 4.19.0 |
2020-06-30 16:36:58 +08:00
| style | The additional style | CSSProperties | - | |
2019-11-20 14:53:43 +08:00
| suffixIcon | The custom suffix icon | ReactNode | - | |
2020-06-30 16:36:58 +08:00
| value | The selected value | string\[] \| number\[] | - | |
2023-12-21 13:39:04 +08:00
| variant | Variants of selector | `outlined` \| `borderless` \| `filled` | `outlined` | 5.13.0 |
2020-06-30 16:36:58 +08:00
| onChange | Callback when finishing cascader select | (value, selectedOptions) => void | - | |
2021-08-31 15:51:02 +08:00
| onDropdownVisibleChange | Callback when popup shown or hidden | (value) => void | - | 4.17.0 |
2021-09-30 11:02:12 +08:00
| multiple | Support multiple or not | boolean | - | 4.17.0 |
2022-03-14 21:07:48 +08:00
| removeIcon | The custom remove icon | ReactNode | - | |
2022-03-29 14:55:39 +08:00
| showCheckedStrategy | The way show selected item in box. ** `SHOW_CHILD` : ** just show child treeNode. ** `Cascader.SHOW_PARENT` :** just show parent treeNode (when all child treeNode under the parent treeNode are checked) | `Cascader.SHOW_PARENT` \| `Cascader.SHOW_CHILD` | `Cascader.SHOW_PARENT` | 4.20.0 |
2023-09-01 23:39:56 +08:00
| searchValue | Set search value, Need work with `showSearch` | string | - | 4.17.0 |
2021-12-30 11:38:48 +08:00
| onSearch | The callback function triggered when input changed | (search: string) => void | - | 4.17.0 |
2021-09-25 16:59:51 +08:00
| dropdownMenuColumnStyle | The style of the drop-down menu column | CSSProperties | - | |
2022-11-19 22:56:58 +08:00
| loadingIcon | The appearance of lazy loading (now is useless) | ReactNode | - | |
2024-03-06 20:04:13 +08:00
| optionRender | Customize the rendering dropdown options | (option: Option) => React.ReactNode | - | 5.16.0 |
2016-09-01 11:08:41 +08:00
2020-11-11 17:05:04 +08:00
### showSearch
2016-09-01 11:08:41 +08:00
2019-07-11 14:14:33 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
2020-06-30 16:36:58 +08:00
| filter | The function will receive two arguments, inputValue and option, if the function returns true, the option will be included in the filtered set; Otherwise, it will be excluded | function(inputValue, path): boolean | - | |
2019-11-20 14:53:43 +08:00
| limit | Set the count of filtered items | number \| false | 50 | |
2020-07-23 17:51:00 +08:00
| matchInputWidth | Whether the width of list matches input, ([how it looks](https://github.com/ant-design/ant-design/issues/25779)) | boolean | true | |
2020-06-30 16:36:58 +08:00
| render | Used to render filtered options | function(inputValue, path): ReactNode | - | |
| sort | Used to sort filtered options | function(a, b, inputValue) | - | |
2016-09-01 11:08:41 +08:00
2019-07-09 19:10:36 +08:00
### Option
```typescript
interface Option {
2020-05-18 19:38:36 +08:00
value: string | number;
2019-07-09 19:10:36 +08:00
label?: React.ReactNode;
disabled?: boolean;
children?: Option[];
2022-02-24 10:53:51 +08:00
// Determines if this is a leaf node(effective when `loadData` is specified).
// `false` will force trade TreeNode as a parent node.
// Show expand icon even if the current node has no children.
isLeaf?: boolean;
2019-07-09 19:10:36 +08:00
}
```
2017-12-01 19:28:41 +08:00
## Methods
2021-09-13 15:59:57 +08:00
| Name | Description | Version |
| ------- | ------------ | ------- |
| blur() | Remove focus | |
| focus() | Get focus | |
2023-04-11 10:25:24 +08:00
## Design Token
< ComponentTokenTable component = "Cascader" > < / ComponentTokenTable >