DatePicker - Vant 4

DatePicker

🗓️ Time travel made easy! Pick any date with style and precision.

📅 Intro

The DatePicker component is your gateway to seamless date selection! 🚀 Whether you're building a booking system, scheduling app, or any date-sensitive feature, this component delivers a smooth and intuitive experience. It pairs beautifully with the Popup component to create elegant date selection modals that users will love! ✨

📦 Install

Get started in seconds! Register the DatePicker component globally via app.use and you're ready to roll! 🎯 Check out our Component Registration guide for more installation options.

import { createApp } from'vue'; import { DatePicker } from'vant'; const app = createApp(); app.use(DatePicker);

🎨 Usage

⚡ Basic Usage

Jump right in with the simplest date picker setup! Perfect for when you need a straightforward date selection without any fuss. 🎪

import { ref } from'vue'; exportdefault { setup() { const currentDate = ref(['2021', '01', '01']); return { minDate: newDate(2020, 0, 1), maxDate: newDate(2025, 5, 1), currentDate, }; }, };

🎛️ Columns Type

Take full control of your date picker's appearance! Use the columns-type prop to customize exactly which date components you want to display. Mix and match to create the perfect picker for your needs! 🎨

For example:

• Pass in ['year'] to select year only - perfect for birth year selection! 🎂
• Pass in ['month'] to select month only - great for monthly reports! 📊
• Pass in ['year', 'month'] to select year and month - ideal for credit card expiry! 💳
• Pass in ['month', 'day'] to select month and day - perfect for recurring events! 🔄

import { ref } from'vue'; exportdefault { setup() { const currentDate = ref(['2021', '01']); const columnsType = ['year', 'month']; return { minDate: newDate(2020, 0, 1), maxDate: newDate(2025, 5, 1), currentDate, columnsType, }; }, };

🎨 Options Formatter

Make your date picker speak your language! Use the formatter function to customize how dates are displayed. Add suffixes, prefixes, or any custom text to make the interface more user-friendly and localized! 🌍

import { ref } from'vue'; exportdefault { setup() { const currentDate = ref(['2021', '01']); const columnsType = ['year', 'month']; constformatter = (type, option) => { if (type === 'year') { option.text += ' Year'; } if (type === 'month') { option.text += 'Month'; } return option; }; return { minDate: newDate(2020, 0, 1), maxDate: newDate(2025, 5, 1), formatter, currentDate, columnsType, }; }, };

🔍 Options Filter

Need to limit available options? The filter function is your best friend! Create custom rules to show only specific dates - perfect for business days, available appointment slots, or any custom date restrictions! 🎯

import { ref } from'vue'; exportdefault { setup() { const currentDate = ref(['2021', '01']); const columnsType = ['year', 'month']; constfilter = (type, options) => { if (type === 'month') { return options.filter((option) =>Number(option.value) % 6 === 0); } return options; }; return { filter, minDate: newDate(2020, 0, 1), maxDate: newDate(2025, 5, 1), currentTime, columnsType, }; }, };

API

Props

Attribute	Description	Type	Default
v-model	Current date	string[]	[]
columns-type	Columns type	string[]	['year', 'month', 'day']
min-date	Min date	Date	Ten years ago on January 1
max-date	Max date	Date	Ten years later on December 31
title	Toolbar title	string	''
confirm-button-text	Text of confirm button	string	Confirm
cancel-button-text	Text of cancel button	string	Cancel
show-toolbar	Whether to show toolbar	boolean	true
loading	Whether to show loading prompt	boolean	false
readonly	Whether to be readonly	boolean	false
filter	Option filter	(type: string, options: PickerOption[], values: string[]) => PickerOption[]	-
formatter	Option formatter	(type: string, option: PickerOption) => PickerOption	-
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 option is changed	{ selectedValues, selectedOptions, selectedIndexes, 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	-

Methods

Use ref to get Picker instance and call instance methods.

Name	Description	Attribute	Return value
confirm	Stop scrolling and emit confirm event	-	-
getSelectedDate	Get current selected date	-	string[]

Types

The component exports the following type definitions:

importtype { DatePickerProps, DatePickerColumnType, DatePickerInstance, } from'vant';

DatePickerInstance is the type of component instance:

import { ref } from'vue'; importtype { DatePickerInstance } from'vant'; const datePickerRef = ref<DatePickerInstance>(); datePickerRef.value?.confirm();

🔗 Related Docs

• Calendar - Full calendar view for date selection
• TimePicker - Time selection component
• Popup - Modal container for date picker
• Field - Input field for date display
• Form - Form validation and submission
• Picker - Base picker component
• ConfigProvider - Global configuration
• Advanced Usage - Advanced implementation patterns