Install

import { createApp } from 'vue';
import { Cascader } from 'vant';

const app = createApp();
app.use(Cascader);

Usage

Basic Usage

<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,
    };
  },
};

Custom Color

<van-cascader
  v-model="cascaderValue"
  title="Select Area"
  :options="options"
  active-color="#1989fa"
  @close="show = false"
  @finish="onFinish"
/>

Async Options

<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';

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) {
        setTimeout(() => {
          options.value[0].children = [
            { text: 'Hangzhou', value: '330100' },
            { text: 'Ningbo', value: '330200' },
          ];
        }, 500);
      }
    };
    const onFinish = ({ selectedOptions }) => {
      show.value = false;
      fieldValue.value = selectedOptions.map((option) => option.text).join('/');
    };

    return {
      show,
      options,
      onFinish,
      fieldValue,
      cascaderValue,
    };
  },
};

Custom Field Names

<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,
    };
  },
};

Custom Content

<van-cascader v-model="code" title="Select Area" :options="options">
  <template #options-top="{ tabIndex }">
    <div class="current-level">Current level is {{ tabIndex }}</div>
  </template>
</van-cascader>

<style>
  .current-level {
    padding: 10px 16px 0;
  }
</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,
    };
  },
};

API

Props

Attribute	Description	Type	Default
title	Title	string	-
value	Value of selected option	string \| number	-
options	Options	CascaderOption[]	`[]`
placeholder	Placeholder of unselected tab	string	`Select`
active-color	Active color	string	`#ee0a24`
swipeable `v3.0.11`	Whether to enable gestures to slide left and right	boolean	`false`
closeable	Whether to show close icon	boolean	`true`
show-header `v3.4.2`	Whether to show header	boolean	`true`
close-icon `v3.0.10`	Close icon name	string	`cross`
field-names `v3.0.4`	Custom the fields of options	object	`{ text: 'text', value: 'value', children: 'children' }`

Data Structure of CascaderOption

Key	Description	Type
text	Option text	string
value	Option value	string \| number
color `v3.1.0`	Text color	string
children	Cascade children	CascaderOption[]
disabled `v3.1.2`	Whether to disable option	boolean
className `v3.1.0`	className for the option	string \| Array \| object

Events

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

Slots

Name	Description	SlotProps
title	Custom title	-
option `v3.1.4`	Custom option text	{ option: CascaderOption, selected: boolean }
options-top `v3.2.7`	Custom the content above the options	{ tabIndex: number }
options-bottom `v3.2.8`	Custom the content below the options	{ tabIndex: number }

Types

The component exports the following type definitions:

import type { CascaderProps, CascaderOption, CascaderFieldNames } from 'vant';

Theming

CSS Variables

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)	-

Cascader

Intro