packages/vant/src/cascader/README.md
The cascader component is used for the selection of multi-level data. The typical scene is the selection of provinces and cities.
Register component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from 'vue';
import { Cascader } from 'vant';
const app = createApp();
app.use(Cascader);
<van-field
v-model="fieldValue"
is-link
readonly
label="Area"
placeholder="Select Area"
@click="show = true"
/>
<van-popup v-model="show" round position="bottom">
<van-cascader
v-model="cascaderValue"
title="Select Area"
:options="options"
@close="show = false"
@finish="onFinish"
/>
</van-popup>
import { ref } from 'vue';
export default {
setup() {
const show = ref(false);
const fieldValue = ref('');
const cascaderValue = ref('');
const options = [
{
text: 'Zhejiang',
value: '330000',
children: [{ text: 'Hangzhou', value: '330100' }],
},
{
text: 'Jiangsu',
value: '320000',
children: [{ text: 'Nanjing', value: '320100' }],
},
];
const onFinish = ({ selectedOptions }) => {
show.value = false;
fieldValue.value = selectedOptions.map((option) => option.text).join('/');
};
return {
show,
options,
onFinish,
fieldValue,
cascaderValue,
};
},
};
<van-cascader
v-model="cascaderValue"
title="Select Area"
:options="options"
active-color="#ee0a24"
@close="show = false"
@finish="onFinish"
/>
<van-field
v-model="fieldValue"
is-link
readonly
label="Area"
placeholder="Select Area"
@click="show = true"
/>
<van-popup v-model="show" round position="bottom">
<van-cascader
v-model="cascaderValue"
title="Select Area"
:options="options"
@close="show = false"
@change="onChange"
@finish="onFinish"
/>
</van-popup>
import { ref } from 'vue';
import { closeToast, showLoadingToast } from 'vant';
export default {
setup() {
const show = ref(false);
const fieldValue = ref('');
const cascaderValue = ref('');
const options = ref([
{
text: 'Zhejiang',
value: '330000',
children: [],
},
]);
const onChange = ({ value }) => {
if (
value === options.value[0].value &&
options.value[0].children.length === 0
) {
showLoadingToast('Loading...');
// mock data request
setTimeout(() => {
options.value[0].children = [
{ text: 'Hangzhou', value: '330100' },
{ text: 'Ningbo', value: '330200' },
];
closeToast();
}, 1000);
}
};
const onFinish = ({ selectedOptions }) => {
show.value = false;
fieldValue.value = selectedOptions.map((option) => option.text).join('/');
};
return {
show,
options,
onFinish,
fieldValue,
cascaderValue,
};
},
};
<van-cascader
v-model="code"
title="Select Area"
:options="options"
:field-names="fieldNames"
/>
import { ref } from 'vue';
export default {
setup() {
const code = ref('');
const fieldNames = {
text: 'name',
value: 'code',
children: 'items',
};
const options = [
{
name: 'Zhejiang',
code: '330000',
items: [{ name: 'Hangzhou', code: '330100' }],
},
{
name: 'Jiangsu',
code: '320000',
items: [{ name: 'Nanjing', code: '320100' }],
},
];
return {
code,
options,
fieldNames,
};
},
};
<van-cascader v-model="code" title="Select Area" :options="options">
<template #options-top="{ tabIndex }">
<div class="current-level">Current level is {{ tabIndex + 1 }}</div>
</template>
</van-cascader>
<style>
.current-level {
font-size: 14px;
padding: 16px 16px 0;
color: var(--van-gray-6);
}
</style>
import { ref } from 'vue';
export default {
setup() {
const code = ref('');
const options = [
{
name: 'Zhejiang',
code: '330000',
items: [{ name: 'Hangzhou', code: '330100' }],
},
{
name: 'Jiangsu',
code: '320000',
items: [{ name: 'Nanjing', code: '320100' }],
},
];
return {
code,
options,
};
},
};
| Attribute | Description | Type | Default |
|---|---|---|---|
| v-model | Value of selected option | string | number | - |
| title | Title | string | - |
| options | Options | CascaderOption[] | [] |
| placeholder | Placeholder of unselected tab | string | Select |
| active-color | Active color | string | #1989fa |
| swipeable | Whether to enable gestures to slide left and right | boolean | true |
| closeable | Whether to show close icon | boolean | true |
| show-header | Whether to show header | boolean | true |
| close-icon | Close icon name | string | cross |
| field-names | Custom the fields of options | CascaderFieldNames | { text: 'text', value: 'value', children: 'children' } |
| Key | Description | Type |
|---|---|---|
| text | Option text | string |
| value | Option value | string | number |
| color | Text color | string |
| children | Cascade children | CascaderOption[] |
| disabled | Whether to disable option | boolean |
| className | className for the option | string | Array | object |
| Event | Description | Arguments |
|---|---|---|
| change | Emitted when active option changed | { value: string | number, selectedOptions: CascaderOption[], tabIndex: number } |
| finish | Emitted when all options is selected | { value: string | number, selectedOptions: CascaderOption[], tabIndex: number } |
| close | Emitted when the close icon is clicked | - |
| click-tab | Emitted when a tab is clicked | activeTab: number, title: string |
| Name | Description | SlotProps |
|---|---|---|
| title | Custom title | - |
| option | Custom option text | { option: CascaderOption, selected: boolean } |
| options-top | Custom the content above the options | { tabIndex: number } |
| options-bottom | Custom the content below the options | { tabIndex: number } |
The component exports the following type definitions:
import type { CascaderProps, CascaderOption, CascaderFieldNames } from 'vant';
The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
| Name | Default Value | Description |
|---|---|---|
| --van-cascader-header-height | 48px | - |
| --van-cascader-header-padding | 0 var(--van-padding-md) | - |
| --van-cascader-title-font-size | var(--van-font-size-lg) | - |
| --van-cascader-title-line-height | 20px | - |
| --van-cascader-close-icon-size | 22px | - |
| --van-cascader-close-icon-color | var(--van-gray-5) | - |
| --van-cascader-selected-icon-size | 18px | - |
| --van-cascader-tabs-height | 48px | - |
| --van-cascader-active-color | var(--van-danger-color) | - |
| --van-cascader-options-height | 384px | - |
| --van-cascader-tab-color | var(--van-text-color) | - |
| --van-cascader-unselected-tab-color | var(--van-text-color-2) | - |