vant/packages/vant/src/picker/README.md

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 { showToast } from 'vant';

export default {
  setup() {
    const columns = [
      { text: 'Delaware', value: 'Delaware' },
      { text: 'Florida', value: 'Florida' },
      { text: 'Wenzhou', value: 'Wenzhou' },
      { text: 'Indiana', value: 'Indiana' },
      { text: 'Maine', value: 'Maine' },
    ];
    const onConfirm = ({ selectedValues }) => {
      showToast(`Value: ${selectedValues.join(',')}`);
    };
    const onChange = ({ selectedValues }) => {
      showToast(`Value: ${selectedValues.join(',')}`);
    };
    const onCancel = () => showToast('Cancel');

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

With Popup

<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 = [
      { text: 'Delaware', value: 'Delaware' },
      { text: 'Florida', value: 'Florida' },
      { text: 'Wenzhou', value: 'Wenzhou' },
      { text: 'Indiana', value: 'Indiana' },
      { text: 'Maine', value: 'Maine' },
    ];
    const result = ref('');
    const showPicker = ref(false);

    const onConfirm = ({ selectedOptions }) => {
      showPicker.value = false;
      fieldValue.value = selectedOptions[0].text;
    };

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

v-model

Using v-model to bind selected values.

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

import { showToast } from 'vant';

export default {
  setup() {
    const columns = [
      { text: 'Delaware', value: 'Delaware' },
      { text: 'Florida', value: 'Florida' },
      { text: 'Wenzhou', value: 'Wenzhou' },
      { text: 'Indiana', value: 'Indiana' },
      { text: 'Maine', value: 'Maine' },
    ];
    const selectedValues = ref(['Wenzhou']);

    return {
      columns,
      selectedValues,
    };
  },
};

Multiple Columns

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

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

    return { columns };
  },
};

Cascade

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

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

    return { columns };
  },
};

Disable option

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

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

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 = [{ text: 'Option', value: 'option' }];
      loading.value = false;
    }, 1000);

    return { columns, loading };
  },
};

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',
      value: 'cityName',
      children: 'cities',
    };

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

API

Props

Attribute	Description	Type	Default
columns	Columns data	PickerOption[] | PickerOption[][]	[]
columns-field-names	custom columns field	object	{ text: 'text', value: 'value', 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
option-height	Option height, supports px vw vh rem unit, default px	number | string	44
visible-option-num	Count of visible columns	number | string	6
swipe-duration	Duration of the momentum animation, unit ms	number | string	1000

Events

Event	Description	Arguments
confirm	Emitted when the confirm button is clicked	{ selectedValues, selectedOptions }
cancel	Emitted when the cancel button is clicked	{ selectedValues, selectedOptions }
change	Emitted when current option is changed	{ selectedValues, selectedOptions, columnIndex }
click-option	Emitted when an option is clicked	{ currentOption, selectedValues, selectedOptions, columnIndex }

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: PickerOption
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-

Data Structure of PickerOption

Key	Description	Type
text	Text	string | number
value	Value of option	string | number
disabled	Whether to disable option	boolean
children	Cascade children options	PickerOption[]
className	ClassName for this option	string | Array | object

Methods

Use ref to get Picker instance and call instance methods.

Name	Description	Attribute	Return value
confirm	Stop scrolling and emit confirm event	-	-
getSelectedOptions	Get current selected options	-	(PickerOption | undefined)[]

Types

The component exports the following type definitions:

import type {
  PickerProps,
  PickerColumn,
  PickerOption,
  PickerInstance,
  PickerFieldNames,
  PickerToolbarPosition,
  PickerCancelEventParams,
  PickerChangeEventParams,
  PickerConfirmEventParams,
} 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	var(--van-background-2)	-
--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-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)	-