2021-09-25 08:51:32 +00:00
---
category: Components
type: Data Entry
title: Cascader
cover: https://gw.alipayobjects.com/zos/alicdn/UdS8y8xyZ/Cascader.svg
---
Cascade selection box.
## When To Use
- 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.
- Chooses cascade items in one float layer for better user experience.
## API
```html
< a-cascader :options = "options" v-model:value = "value" / >
```
2022-01-21 13:58:10 +00:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| allowClear | whether allow clear | boolean | true | |
| autofocus | get focus when component mounted | boolean | false | |
2022-03-12 01:56:32 +00:00
| changeOnSelect | (Work on single select) change value on each selection if set to true, see above demo for details | boolean | false | |
2022-01-21 13:58:10 +00:00
| disabled | whether disabled select | boolean | false | |
2022-03-12 01:56:32 +00:00
| displayRender | render function of displaying selected options, you can use #displayRender ="{labels, selectedOptions}". | `({labels, selectedOptions}) => VNode` | `labels => labels.join(' / ')` | |
| dropdownClassName | additional className of popup overlay | string | - | 3.0 |
| dropdownStyle | additional style of popup overlay | CSSProperties | {} | 3.0 |
| expandIcon | Customize the current item expand icon | slot | - | 3.0 |
2022-01-21 13:58:10 +00:00
| expandTrigger | expand current item when click or hover, one of 'click' 'hover' | string | 'click' | |
| 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. | Function(triggerNode) | () => document.body | |
| loadData | To load option lazily, and it cannot work with `showSearch` | `(selectedOptions) => void` | - | |
2022-03-12 01:56:32 +00:00
| maxTagCount | Max tag count to show. `responsive` will cost render performance | number \| `responsive` | - | 3.0 |
| maxTagPlaceholder | Placeholder for not showing tags | v-slot \| function(omittedValues) | - | 3.0 |
| multiple | Support multiple or not | boolean | - | 3.0 |
2022-01-21 13:58:10 +00:00
| notFoundContent | Specify content to show when no result matches. | string \| slot | 'Not Found' | |
2022-03-12 01:56:32 +00:00
| open | set visible of cascader popup | boolean | - | 3.0 |
| options | data options of cascade | [Option ](#option )\[] | - | |
2022-01-21 13:58:10 +00:00
| placeholder | input placeholder | string | 'Please select' | |
2022-03-12 01:56:32 +00:00
| placement | use preset popup align config from builtinPlacements: `bottomLeft` `bottomRight` `topLeft` `topRight` | string | `bottomLeft` | 3.0 |
| searchValue | Set search value, Need work with `showSearch` | string | - | 3.0 |
2022-01-21 13:58:10 +00:00
| showSearch | Whether show search input in single mode. | boolean \| [object ](#showsearch ) | false | |
| size | input size, one of `large` `default` `small` | string | `default` | |
| suffixIcon | The custom suffix icon | string \| VNode \| slot | - | |
| tagRender | Customize tag render when `multiple` | slot | - | 3.0 |
2022-03-12 01:56:32 +00:00
| value(v-model) | selected value | string\[] \| number\[] | - | |
2021-09-25 08:51:32 +00:00
### showSearch
Fields in `showSearch` :
| Property | Description | Type | Default |
| --- | --- | --- | --- |
| 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` | |
| limit | Set the count of filtered items | number \| false | 50 |
| matchInputWidth | Whether the width of result list equals to input's | boolean | |
| render | Used to render filtered options, you can use #showSearchRender ="{inputValue, path}" | `function({inputValue, path}): VNode` | |
| sort | Used to sort filtered options. | `function(a, b, inputValue)` | |
### events
2022-03-12 01:56:32 +00:00
| Events Name | Description | Arguments | version | |
2021-09-25 08:51:32 +00:00
| --- | --- | --- | --- | --- |
| change | callback when finishing cascader select | `(value, selectedOptions) => void` | - | |
2022-01-21 13:58:10 +00:00
| dropdownVisibleChange | callback when popup shown or hidden | `(value) => void` | - | 3.0 |
2021-09-25 08:51:32 +00:00
| search | callback when input value change | `(value) => void` | - | 1.5.4 |
### Option
```ts
interface Option {
value: string | number;
label?: VNode;
disabled?: boolean;
children?: Option[];
2022-03-17 02:24:49 +00: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;
2021-09-25 08:51:32 +00:00
}
```
## Methods
| Name | Description |
| ------- | ------------ |
| blur() | remove focus |
| focus() | get focus |