vant/src/picker

Picker

Intro

The picker component is usually used with Popup Component.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

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="state.columns" :loading="state.loading" />

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      columns: [],
      loading: true,
    });

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

    return { state };
  },
};

With Popup

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

import { reactive } from 'vue';

export default {
  setup() {
    const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];
    const state = reactive({
      value: '',
      showPicker: false,
    });

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

    return {
      state,
      columns,
      onConfirm,
    };
  },
};

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	Single column：current value，current index Multiple columns：current values，current indexes
cancel	Emitted when click cancel button	Single column：current value，current index Multiple columns：current values，current indexes
change	Emitted when current option changed	Single column：Picker instance, current value，current index Multiple columns：Picker instance, current values，column index

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

Get the type definition of the Picker instance through PickerInstance.

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

const pickerRef = ref<PickerInstance>();

pickerRef.value?.confirm();

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-white)	-
--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-gray-6)	-
--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-black)	-
--van-picker-option-disabled-opacity	0.3	-
--van-picker-loading-icon-color	var(--van-primary-color)	-
--van-picker-loading-mask-color	rgba(255, 255, 255, 0.9)	-