Picker - Vant 4

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

import { showToast } from'vant'; exportdefault { setup() { const columns = [ { text: 'Delaware', value: 'Delaware' }, { text: 'Florida', value: 'Florida' }, { text: 'Wenzhou', value: 'Wenzhou' }, { text: 'Indiana', value: 'Indiana' }, { text: 'Maine', value: 'Maine' }, ]; constonConfirm = ({ selectedValues }) => { showToast(`Value: ${selectedValues.join(',')}`); }; constonChange = ({ selectedValues }) => { showToast(`Value: ${selectedValues.join(',')}`); }; constonCancel = () => showToast('Cancel'); return { columns, onChange, onCancel, onConfirm, }; }, };

With Popup

import { ref } from'vue'; exportdefault { setup() { const columns = [ { text: 'Delaware', value: 'Delaware' }, { text: 'Florida', value: 'Florida' }, { text: 'Wenzhou', value: 'Wenzhou' }, { text: 'Indiana', value: 'Indiana' }, { text: 'Maine', value: 'Maine' }, ]; const fieldValue = ref(''); const pickerValue = ref<Numeric[]>([]); const showPicker = ref(false); constonConfirm = ({ selectedValues, selectedOptions }) => { showPicker.value = false; pickerValue.value = selectedValues; fieldValue.value = selectedOptions[0].text; }; return { columns, onConfirm, fieldValue, showPicker, }; }, };

v-model

Using v-model to bind selected values.

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

exportdefault { 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

exportdefault { 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

exportdefault { 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.

import { ref } from'vue'; exportdefault { setup() { const columns = ref([]); const loading = ref(true); setTimeout(() => { columns.value = [{ text: 'Option', value: 'option' }]; loading.value = false; }, 1000); return { columns, loading }; }, };

Empty content

When the data is empty, you can use the empty slot to customize the empty content.

Custom Columns Field

exportdefault { 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
v-model	values of chosen option	*number[]	string[]*
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, setting it as an empty string can hide the button	string	Confirm
cancel-button-text	Text of cancel button, setting it as an empty string can hide the button	string	Cancel
toolbar-position	Toolbar position, cat be set to bottom	string	top
loading	Whether to show loading prompt	boolean	false
readonly	Whether to be readonly	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*
visible-option-num	Count of visible columns	*number	string*
swipe-duration	Duration of the momentum animation, unit ms	*number	string*

Events

Event	Description	Arguments
confirm	Emitted when the confirm button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
cancel	Emitted when the cancel button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
change	Emitted when current selected option is changed	{ selectedValues, selectedOptions,selectedIndexes, columnIndex }
click-option	Emitted when an option is clicked	{ currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex }
scroll-into v4.2.1	Emitted when an option is scrolled into the middle selection area by clicking or dragging	{ currentOption, columnIndex }

Slots

Name	Description	SlotProps
toolbar	Custom toolbar content	-
title	Custom title	-
confirm	Custom confirm button text	-
cancel	Custom cancel button text	-
option	Custom option content	option: PickerOption, index: number
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-
empty v4.9.10	Custom empty content	-

Data Structure of PickerOption

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

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

Types

The component exports the following type definitions:

importtype { PickerProps, PickerColumn, PickerOption, PickerInstance, PickerFieldNames, PickerToolbarPosition, PickerCancelEventParams, PickerChangeEventParams, PickerConfirmEventParams, } from'vant';

PickerInstance is the type of component instance:

import { ref } from'vue'; importtype { 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-primary-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)	-