The picker component is usually used with Popup Component.
\nRegister component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from 'vue';\nimport { Picker } from 'vant';\n\nconst app = createApp();\napp.use(Picker);\n<van-picker\n title="Title"\n :columns="columns"\n @confirm="onConfirm"\n @cancel="onCancel"\n @change="onChange"\n/>\nimport { showToast } from 'vant';\n\nexport default {\n setup() {\n const columns = [\n { text: 'Delaware', value: 'Delaware' },\n { text: 'Florida', value: 'Florida' },\n { text: 'Wenzhou', value: 'Wenzhou' },\n { text: 'Indiana', value: 'Indiana' },\n { text: 'Maine', value: 'Maine' },\n ];\n const onConfirm = ({ selectedValues }) => {\n showToast(`Value: ${selectedValues.join(',')}`);\n };\n const onChange = ({ selectedValues }) => {\n showToast(`Value: ${selectedValues.join(',')}`);\n };\n const onCancel = () => showToast('Cancel');\n\n return {\n columns,\n onChange,\n onCancel,\n onConfirm,\n };\n },\n};\n<van-field\n v-model="fieldValue"\n is-link\n readonly\n label="City"\n placeholder="Choose City"\n @click="showPicker = true"\n/>\n<van-popup v-model:show="showPicker" round position="bottom">\n <van-picker\n title="Title"\n :columns="columns"\n @cancel="showPicker = false"\n @confirm="onConfirm"\n />\n</van-popup>\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const columns = [\n { text: 'Delaware', value: 'Delaware' },\n { text: 'Florida', value: 'Florida' },\n { text: 'Wenzhou', value: 'Wenzhou' },\n { text: 'Indiana', value: 'Indiana' },\n { text: 'Maine', value: 'Maine' },\n ];\n const fieldValue = ref('');\n const showPicker = ref(false);\n\n const onConfirm = ({ selectedOptions }) => {\n showPicker.value = false;\n fieldValue.value = selectedOptions[0].text;\n };\n\n return {\n columns,\n onConfirm,\n fieldValue,\n showPicker,\n };\n },\n};\nUsing v-model to bind selected values.
<van-picker v-model="selectedValues" title="Title" :columns="columns" />\nimport { showToast } from 'vant';\n\nexport default {\n setup() {\n const columns = [\n { text: 'Delaware', value: 'Delaware' },\n { text: 'Florida', value: 'Florida' },\n { text: 'Wenzhou', value: 'Wenzhou' },\n { text: 'Indiana', value: 'Indiana' },\n { text: 'Maine', value: 'Maine' },\n ];\n const selectedValues = ref(['Wenzhou']);\n\n return {\n columns,\n selectedValues,\n };\n },\n};\n<van-picker title="Title" :columns="columns" />\nexport default {\n setup() {\n const columns = [\n [\n { text: 'Monday', value: 'Monday' },\n { text: 'Tuesday', value: 'Tuesday' },\n { text: 'Wednesday', value: 'Wednesday' },\n { text: 'Thursday', value: 'Thursday' },\n { text: 'Friday', value: 'Friday' },\n ],\n [\n { text: 'Morning', value: 'Morning' },\n { text: 'Afternoon', value: 'Afternoon' },\n { text: 'Evening', value: 'Evening' },\n ],\n ];\n\n return { columns };\n },\n};\n<van-picker title="Title" :columns="columns" />\nexport default {\n setup() {\n const columns = [\n {\n text: 'Zhejiang',\n value: 'Zhejiang',\n children: [\n {\n text: 'Hangzhou',\n value: 'Hangzhou',\n children: [\n { text: 'Xihu', value: 'Xihu' },\n { text: 'Yuhang', value: 'Yuhang' },\n ],\n },\n {\n text: 'Wenzhou',\n value: 'Wenzhou',\n children: [\n { text: 'Lucheng', value: 'Lucheng' },\n { text: 'Ouhai', value: 'Ouhai' },\n ],\n },\n ],\n },\n {\n text: 'Fujian',\n value: 'Fujian',\n children: [\n {\n text: 'Fuzhou',\n value: 'Fuzhou',\n children: [\n { text: 'Gulou', value: 'Gulou' },\n { text: 'Taijiang', value: 'Taijiang' },\n ],\n },\n {\n text: 'Xiamen',\n value: 'Xiamen',\n children: [\n { text: 'Siming', value: 'Siming' },\n { text: 'Haicang', value: 'Haicang' },\n ],\n },\n ],\n },\n ];\n\n return { columns };\n },\n};\n<van-picker :columns="columns" />\nexport default {\n setup() {\n const columns = [\n { text: 'Delaware', value: 'Delaware', disabled: true },\n { text: 'Florida', value: 'Florida' },\n { text: 'Wenzhou', value: 'Wenzhou' },\n ];\n return { columns };\n },\n};\nWhen Picker columns data is acquired asynchronously, use loading prop to show loading prompt.
<van-picker title="Title" :columns="columns" :loading="loading" />\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const columns = ref([]);\n const loading = ref(true);\n\n setTimeout(() => {\n columns.value = [{ text: 'Option', value: 'option' }];\n loading.value = false;\n }, 1000);\n\n return { columns, loading };\n },\n};\n<van-picker\n :title="Title"\n :columns="columns"\n :columns-field-names="customFieldName"\n/>\nexport default {\n setup() {\n const columns = [\n {\n cityName: 'Zhejiang',\n cities: [\n {\n cityName: 'Hangzhou',\n cities: [{ cityName: 'Xihu' }, { cityName: 'Yuhang' }],\n },\n {\n cityName: 'Wenzhou',\n cities: [{ cityName: 'Lucheng' }, { cityName: 'Ouhai' }],\n },\n ],\n },\n {\n cityName: 'Fujian',\n cities: [\n {\n cityName: 'Fuzhou',\n cities: [{ cityName: 'Gulou' }, { cityName: 'Taijiang' }],\n },\n {\n cityName: 'Xiamen',\n cities: [{ cityName: 'Siming' }, { cityName: 'Haicang' }],\n },\n ],\n },\n ];\n\n const customFieldName = {\n text: 'cityName',\n value: 'cityName',\n children: 'cities',\n };\n\n return {\n columns,\n customFieldName,\n };\n },\n};\n| Attribute | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| v-model | \nvalues of chosen option | \nnumber[] | string[] | \n- | \n
| columns | \nColumns data | \nPickerOption[] | PickerOption[][] | \n[] | \n
| columns-field-names | \ncustom columns field | \nobject | \n{ text: \'text\', value: \'value\', children: \'children\' } | \n
| title | \nToolbar title | \nstring | \n- | \n
| confirm-button-text | \nText of confirm button, setting it as an empty string can hide the button | \nstring | \nConfirm | \n
| cancel-button-text | \nText of cancel button, setting it as an empty string can hide the button | \nstring | \nCancel | \n
| toolbar-position | \nToolbar position, cat be set to bottom | \nstring | \ntop | \n
| loading | \nWhether to show loading prompt | \nboolean | \nfalse | \n
| readonly | \nWhether to be readonly | \nboolean | \nfalse | \n
| show-toolbar | \nWhether to show toolbar | \nboolean | \ntrue | \n
| allow-html | \nWhether to allow HTML in option text | \nboolean | \nfalse | \n
| option-height | \nOption height, supports px vw vh rem unit, default px | \nnumber | string | \n44 | \n
| visible-option-num | \nCount of visible columns | \nnumber | string | \n6 | \n
| swipe-duration | \nDuration of the momentum animation, unit ms | \nnumber | string | \n1000 | \n
| Event | \nDescription | \nArguments | \n
|---|---|---|
| confirm | \nEmitted when the confirm button is clicked | \n{ selectedValues, selectedOptions, selectedIndexes } | \n
| cancel | \nEmitted when the cancel button is clicked | \n{ selectedValues, selectedOptions, selectedIndexes } | \n
| change | \nEmitted when current selected option is changed | \n{ selectedValues, selectedOptions,selectedIndexes, columnIndex } | \n
| click-option | \nEmitted when an option is clicked | \n{ currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex } | \n
scroll-into v4.2.1 | \nEmitted when an option is scrolled into the middle selection area by clicking or dragging | \n{ currentOption, columnIndex } | \n
| Name | \nDescription | \nSlotProps | \n
|---|---|---|
| toolbar | \nCustom toolbar content | \n- | \n
| title | \nCustom title | \n- | \n
| confirm | \nCustom confirm button text | \n- | \n
| cancel | \nCustom cancel button text | \n- | \n
| option | \nCustom option content | \noption: PickerOption, index: number | \n
| columns-top | \nCustom content above columns | \n- | \n
| columns-bottom | \nCustom content below columns | \n- | \n
| Key | \nDescription | \nType | \n
|---|---|---|
| text | \nText | \nstring | number | \n
| value | \nValue of option | \nstring | number | \n
| disabled | \nWhether to disable option | \nboolean | \n
| children | \nCascade children options | \nPickerOption[] | \n
| className | \nClassName for this option | \nstring | Array | object | \n
Use ref to get Picker instance and call instance methods.
\n| Name | \nDescription | \nAttribute | \nReturn value | \n
|---|---|---|---|
| confirm | \nStop scrolling and emit confirm event | \n- | \n- | \n
| getSelectedOptions | \nGet current selected options | \n- | \n(PickerOption | undefined)[] | \n
The component exports the following type definitions:
\nimport type {\n PickerProps,\n PickerColumn,\n PickerOption,\n PickerInstance,\n PickerFieldNames,\n PickerToolbarPosition,\n PickerCancelEventParams,\n PickerChangeEventParams,\n PickerConfirmEventParams,\n} from 'vant';\nPickerInstance is the type of component instance:
import { ref } from 'vue';\nimport type { PickerInstance } from 'vant';\n\nconst pickerRef = ref<PickerInstance>();\n\npickerRef.value?.confirm();\nThe component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
\n| Name | \nDefault Value | \nDescription | \n
|---|---|---|
| --van-picker-background | \nvar(--van-background-2) | \n- | \n
| --van-picker-toolbar-height | \n44px | \n- | \n
| --van-picker-title-font-size | \nvar(--van-font-size-lg) | \n- | \n
| --van-picker-title-line-height | \nvar(--van-line-height-md) | \n- | \n
| --van-picker-action-padding | \n0 var(--van-padding-md) | \n- | \n
| --van-picker-action-font-size | \nvar(--van-font-size-md) | \n- | \n
| --van-picker-confirm-action-color | \nvar(--van-primary-color) | \n- | \n
| --van-picker-cancel-action-color | \nvar(--van-text-color-2) | \n- | \n
| --van-picker-option-padding | \n0 var(--van-padding-base) | \n- | \n
| --van-picker-option-font-size | \nvar(--van-font-size-lg) | \n- | \n
| --van-picker-option-text-color | \nvar(--van-text-color) | \n- | \n
| --van-picker-option-disabled-opacity | \n0.3 | \n- | \n
| --van-picker-mask-color | \nlinear-gradient | \n- | \n
| --van-picker-loading-icon-color | \nvar(--van-primary-color) | \n- | \n
| --van-picker-loading-mask-color | \nrgba(255, 255, 255, 0.9) | \n- | \n