Install

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

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

Usage

Basic Usage

<van-picker
  title="Title"
  :columns="columns"
  @confirm="onConfirm"
  @cancel="onCancel"
  @change="onChange"
/>

import { Toast } from 'vant';

export default {
  setup() {
    const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];

    const onConfirm = (value, index) => {
      Toast(\`Value: \${value}, Index: \${index}\`);
    };
    const onChange = (value, index) => {
      Toast(\`Value: \${value}, Index: \${index}\`);
    };
    const onCancel = () => Toast('Cancel');

    return {
      columns,
      onChange,
      onCancel,
      onConfirm,
    };
  },
};

Default Index

<van-picker title="Title" :columns="columns" :default-index="2" />

Multiple Columns

<van-picker title="Title" :columns="columns" />

export default {
  setup() {
    const columns = [
      {
        values: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
        defaultIndex: 2,
      },
      {
        values: ['Morning', 'Afternoon', 'Evening'],
        defaultIndex: 1,
      },
    ];

    return { columns };
  },
};

Cascade

<van-picker title="Title" :columns="columns" />

export default {
  setup() {
    const columns = [
      {
        text: 'Zhejiang',
        children: [
          {
            text: 'Hangzhou',
            children: [{ text: 'Xihu' }, { text: 'Yuhang' }],
          },
          {
            text: 'Wenzhou',
            children: [{ text: 'Lucheng' }, { text: 'Ouhai' }],
          },
        ],
      },
      {
        text: 'Fujian',
        children: [
          {
            text: 'Fuzhou',
            children: [{ text: 'Gulou' }, { text: 'Taijiang' }],
          },
          {
            text: 'Xiamen',
            children: [{ text: 'Siming' }, { text: 'Haicang' }],
          },
        ],
      },
    ];

    return { columns };
  },
};

Disable option

<van-picker :columns="columns" />

export default {
  setup() {
    const columns = [
      { text: 'Delaware', disabled: true },
      { text: 'Florida' },
      { text: 'Georqia' },
    ];

    return { columns };
  },
};

Set Column Values

<van-picker ref="picker" title="Title" :columns="columns" @change="onChange" />

import { ref } from 'vue';

export default {
  setup() {
    const picker = ref(null);

    const states = {
      Group1: ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'],
      Group2: ['Alabama', 'Kansas', 'Louisiana', 'Texas'],
    };
    const columns = [
      { values: Object.keys(states) },
      { values: states.Group1 },
    ];

    const onChange = (values) => {
      picker.value.setColumnValues(1, states[values[0]]);
    };

    return {
      picker,
      columns,
      onChange,
    };
  },
};

Loading

When Picker columns data is acquired asynchronously, use loading prop to show loading prompt.

<van-picker title="Title" :columns="columns" :loading="loading" />

import { ref } from 'vue';

export default {
  setup() {
    const columns = ref([]);
    const loading = ref(true);

    setTimeout(() => {
      columns.value = ['Option'];
      loading.value = false;
    }, 1000);

    return { columns, loading };
  },
};

<van-field
  v-model="result"
  is-link
  readonly
  label="City"
  placeholder="Choose City"
  @click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
  <van-picker
    title="Title"
    :columns="columns"
    @cancel="showPicker = false"
    @confirm="onConfirm"
  />
</van-popup>

import { ref } from 'vue';

export default {
  setup() {
    const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];
    const result = ref('');
    const showPicker = ref(false);

    const onConfirm = (value) => {
      result.value = value;
      showPicker.value = false;
    };

    return {
      result,
      columns,
      onConfirm,
      showPicker,
    };
  },
};

Custom Columns Field

<van-picker
  :title="Title"
  :columns="columns"
  :columns-field-names="customFieldName"
/>

export default {
  setup() {
    const columns = [
      {
        cityName: 'Zhejiang',
        cities: [
          {
            cityName: 'Hangzhou',
            cities: [{ cityName: 'Xihu' }, { cityName: 'Yuhang' }],
          },
          {
            cityName: 'Wenzhou',
            cities: [{ cityName: 'Lucheng' }, { cityName: 'Ouhai' }],
          },
        ],
      },
      {
        cityName: 'Fujian',
        cities: [
          {
            cityName: 'Fuzhou',
            cities: [{ cityName: 'Gulou' }, { cityName: 'Taijiang' }],
          },
          {
            cityName: 'Xiamen',
            cities: [{ cityName: 'Siming' }, { cityName: 'Haicang' }],
          },
        ],
      },
    ];

    const customFieldName = {
      text: 'cityName',
      children: 'cities',
    };

    return {
      columns,
      customFieldName,
    };
  },
};

API

Props

Attribute	Description	Type	Default
columns	Columns data	Column[]	`[]`
columns-field-names	custom columns field	object	`{ text: 'text', values: 'values', children: 'children' }`
title	Toolbar title	string	-
confirm-button-text	Text of confirm button	string	`Confirm`
cancel-button-text	Text of cancel button	string	`Cancel`
toolbar-position	Toolbar position, cat be set to `bottom`	string	`top`
loading	Whether to show loading prompt	boolean	`false`
show-toolbar	Whether to show toolbar	boolean	`true`
allow-html	Whether to allow HTML in option text	boolean	`false`
default-index	Default value index of single column picker	number \| string	`0`
item-height	Option height, supports `px` `vw` `vh` `rem` unit, default `px`	number \| string	`44`
visible-item-count	Count of visible columns	number \| string	`6`
swipe-duration	Duration of the momentum animation, unit `ms`	number \| string	`1000`

Events

Picker events will pass different parameters according to the columns are single or multiple

Event	Description	Arguments
confirm	Emitted when click confirm button. Notice: the arguments return an array when the multiple columns mode.	currentValue: PickerOption \| PickerOption[], currentIndex: number \| number[]
cancel	Emitted when click cancel button. Notice: the arguments return an array when the multiple columns mode.	currentValue: PickerOption \| PickerOption[], currentIndex: number \| number[]
change	Emitted when current option changed. Notice: the arguments return an array when the multiple columns mode.	currentValue: PickerOption \| PickerOption[], currentIndex: number \| number[]

Slots

Name	Description	SlotProps
toolbar `3.1.2`	Custom toolbar content	-
title	Custom title	-
confirm	Custom confirm button text	-
cancel	Custom cancel button text	-
option	Custom option content	option: string \| object
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-

Data Structure of Column

Key	Description	Type
values	Value of column	Array<string \| number>
defaultIndex	Default value index	number
className	ClassName for this column	string \| Array \| object
children	Cascade children	Column

Methods

Use ref to get Picker instance and call instance methods.

Name	Description	Attribute	Return value
getValues	Get current values of all columns	-	values
setValues	Set current values of all columns	values	-
getIndexes	Get current indexes of all columns	-	indexes
setIndexes	Set current indexes of all columns	indexes	-
getColumnValue	Get current value of the column	columnIndex	value
setColumnValue	Set current value of the column	columnIndex, value	-
getColumnIndex	Get current index of the column	columnIndex	optionIndex
setColumnIndex	Set current index of the column	columnIndex, optionIndex	-
getColumnValues	Get columns data of the column	columnIndex	values
setColumnValues	Set columns data of the column	columnIndex, values	-
confirm	Stop scrolling and emit confirm event	-	-

Types

The component exports the following type definitions:

import type {
  PickerProps,
  PickerColumn,
  PickerOption,
  PickerInstance,
  PickerFieldNames,
  PickerObjectColumn,
  PickerObjectOption,
  PickerToolbarPosition,
} from 'vant';

PickerInstance is the type of component instance:

import { ref } from 'vue';
import type { PickerInstance } from 'vant';

const pickerRef = ref<PickerInstance>();

pickerRef.value?.confirm();

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-picker-background-color	var(--van-background-color-light)	-
--van-picker-toolbar-height	44px	-
--van-picker-title-font-size	var(--van-font-size-lg)	-
--van-picker-title-line-height	var(--van-line-height-md)	-
--van-picker-action-padding	0 var(--van-padding-md)	-
--van-picker-action-font-size	var(--van-font-size-md)	-
--van-picker-confirm-action-color	var(--van-text-link-color)	-
--van-picker-cancel-action-color	var(--van-text-color-2)	-
--van-picker-option-padding	0 var(--van-padding-base)	-
--van-picker-option-font-size	var(--van-font-size-lg)	-
--van-picker-option-text-color	var(--van-text-color)	-
--van-picker-option-disabled-opacity	0.3	-
--van-picker-mask-color	linear-gradient	-
--van-picker-loading-icon-color	var(--van-primary-color)	-
--van-picker-loading-mask-color	rgba(255, 255, 255, 0.9)	-

Picker

Intro