vant/src/cascader

Cascader

Intro

The cascader component is used for the selection of multi-level data. The typical scene is the selection of provinces and cities.

Install

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

Usage

Basic Usage

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="Area"
  placeholder="Select Area"
  @click="state.show = true"
/>
<van-popup v-model="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="Select Area"
    :options="options"
    @close="state.show = false"
    @finish="onFinish"
  />
</van-popup>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      show: false,
      fieldValue: '',
      cascaderValue: '',
    });
    const options = [
      {
        text: 'Zhejiang',
        value: '330000',
        children: [{ text: 'Hangzhou', value: '330100' }],
      },
      {
        text: 'Jiangsu',
        value: '320000',
        children: [{ text: 'Nanjing', value: '320100' }],
      },
    ];
    const onFinish = ({ selectedOptions }) => {
      state.show = false;
      state.fieldValue = selectedOptions.map((option) => option.text).join('/');
    };

    return {
      state,
      options,
      onFinish,
    };
  },
};

Custom Color

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

Async Options

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="Area"
  placeholder="Select Area"
  @click="state.show = true"
/>
<van-popup v-model="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="Select Area"
    :options="state.options"
    @close="state.show = false"
    @change="onChange"
    @finish="onFinish"
  />
</van-popup>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      show: false,
      fieldValue: '',
      cascaderValue: '',
      options: [
        {
          text: 'Zhejiang',
          value: '330000',
          children: [],
        },
      ],
    });
    const onChange = ({ value }) => {
      if (value === state.options[0].value) {
        setTimeout(() => {
          state.options[0].children = [
            { text: 'Hangzhou', value: '330100' },
            { text: 'Ningbo', value: '330200' },
          ];
        }, 500);
      }
    };
    const onFinish = ({ selectedOptions }) => {
      state.show = false;
      state.fieldValue = selectedOptions.map((option) => option.text).join('/');
    };

    return {
      state,
      onChange,
      onFinish,
    };
  },
};

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

API

Props

Attribute	Description	Type	Default
title	Title	string	-
value	Value of selected option	string | number	-
options	Options	Option[]	[]
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
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' }

Events

Event	Description	Arguments
change	Emitted when active option changed	{ value, selectedOptions, tabIndex }
finish	Emitted when all options is selected	{ value, selectedOptions, tabIndex }
close	Emitted when the close icon is clicked	-
click-tab	Emitted when a tab is clicked	activeTab: number, title: string

Slots

Name	Description
title	Custom title

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-gary-5)	-
--van-cascader-close-icon-active-color	var(--van-gary-6)	-
--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-gary-6)	-