2016-07-21 10:09:01 +08:00
---
category: Components
2016-11-09 14:43:32 +08:00
type: Data Entry
2016-07-21 10:09:01 +08:00
title: Cascader
2020-06-05 13:50:09 +08:00
cover: https://gw.alipayobjects.com/zos/alicdn/UdS8y8xyZ/Cascader.svg
2016-07-21 10:09:01 +08:00
---
Cascade selection box.
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
## API
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 |
| --- | --- | --- | --- | --- |
| allowClear | whether allow clear | boolean | true | |
| autoFocus | get focus when component mounted | boolean | false | |
2020-02-06 10:02:02 +08:00
| bordered | whether has border style | boolean | true | |
2019-07-11 14:14:33 +08:00
| changeOnSelect | change value on each selection if set to true, see above demo for details | boolean | false | |
| className | additional css class | string | - | |
2020-05-18 19:58:46 +08:00
| defaultValue | initial selected value | string\[] \| number\[] | \[] | |
2019-07-11 14:14:33 +08:00
| disabled | whether disabled select | boolean | false | |
| displayRender | render function of displaying selected options | `(label, selectedOptions) => ReactNode` | `label => label.join(' / ')` | |
2020-06-17 23:18:14 +08:00
| expandTrigger | expand current item when click or hover, one of 'click' 'hover' | string | `click` | |
2020-06-28 22:41:59 +08:00
| expandIcon | customize the current item expand icon | ReactNode | - | 4.4.0 |
2019-11-20 14:53:43 +08:00
| fieldNames | custom field name for label and value and children | object | `{ label: 'label', value: 'value', children: 'children' }` | |
2019-07-11 14:14:33 +08:00
| 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` | - | |
2020-06-17 23:18:14 +08:00
| notFoundContent | Specify content to show when no result matches. | string | `Not Found` | |
2019-07-11 14:14:33 +08:00
| options | data options of cascade | [Option ](#Option )[] | - | |
| placeholder | input placeholder | string | 'Please select' | |
| popupClassName | additional className of popup overlay | string | - | |
| popupPlacement | use preset popup align config from builtinPlacements： `bottomRight` `topLeft` `topRight` | string | `bottomLeft` | |
| popupVisible | set visible of cascader popup | boolean | - | |
| showSearch | Whether show search input in single mode. | boolean\|object | false | |
2020-03-01 18:24:59 +08:00
| size | input size | `large` \| `middle` \| `small` | | |
2020-04-28 14:09:54 +08:00
| style | additional style | CSSProperties | - | |
2019-11-20 14:53:43 +08:00
| suffixIcon | The custom suffix icon | ReactNode | - | |
2020-05-18 19:58:46 +08:00
| value | selected value | string\[] \| number\[] | - | |
2020-06-28 22:41:59 +08:00
| dropdownRender | Customize dropdown content | `(menus: ReactNode) => ReactNode` | - | 4.4.0 |
2019-07-11 14:14:33 +08:00
| onChange | callback when finishing cascader select | `(value, selectedOptions) => void` | - | |
| onPopupVisibleChange | callback when popup shown or hidden | `(value) => void` | - | |
2016-09-01 11:08:41 +08:00
Fields in `showSearch` :
2019-07-11 14:14:33 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| 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 | |
2019-07-11 14:14:33 +08:00
| matchInputWidth | Whether the width of result list equals to input's | boolean | | |
| 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[];
}
```
2017-12-01 19:28:41 +08:00
## Methods
2019-07-11 14:14:33 +08:00
| Name | Description | Version |
| ------- | ------------ | ------- |
| blur() | remove focus | |
| focus() | get focus | |
