🌏 Translated with the assistance of DeepSeek and ChatGPT

DatePicker

A control for selecting a date.

PS: DatePicker, TimePicker, and DateTimePicker are likely the same component internally.

Basic Usage

Pass modelValue to enter controlled mode. If not passed or undefined, it will be uncontrolled mode, and you can pass the defaultValue prop as the default value.

Hide source code

Date Range

Hide source code

Year Selection

Hide source code

Month Selection

Hide source code

Quarter Selection

Hide source code

Week Selection

Hide source code

Quick Access

Date

Hide source code

Custom Separator

TO

Hide source code

Custom Formatting

Set the formatting template via template. Additionally, you can use format and parse to customize formatting and parsing functions. When the date string fails to parse, the component will keep the previous input value.

Hide source code

More Options

DatePicker also supports most of the features of the Input component.

Disabled, Readonly, Loading & Clearable

Shape

Size

Slot

prefix

suffix

Composite

Start:

Status

Expose

Hide source code

Formatter

The component supports time formatting templates based on regular expression matching. The following template tokens can be used to parse various parts of a time string.

Token	Regex Pattern	Description
YYYY	(-?\d{4,6})	Year, supports 4 to 6 digits, may include a minus sign (e.g., for BC)
YY	(\d{2})	Last two digits of the year
MM	(\d{2})	Month, two digits (01-12)
DD	(\d{2})	Day of month, two digits (01-31)
HH	(\d{2})	Hour (24-hour clock), two digits (00-23)
hh	(\d{2})	Hour (12-hour clock), two digits (01-12)
mm	(\d{2})	Minute, two digits (00-59)
ss	(\d{2})	Second, two digits (00-59)
SSS	(\d{3})	Millisecond, three digits (000-999)
A	(AM|PM)	AM/PM marker, uppercase AM or PM
ww	(\d{2})	Week number, week of the year, two digits (01-53, following ISO week date rules)
Q	(\d{1})	Quarter, one digit (1-4)

Text enclosed in square brackets [] will be extracted and preserved as-is. For example, YYYY-[Q]Q produces 2026-Q1, where the Q inside brackets remains literal.

Week calculation follows the ISO 8601 standard: the week starts on Monday, and the first week of the year is the week that contains the first Thursday of that year.

API

DatePickerProps

Attribute	Type	Optional	Default	Description	Version
modelValue	Date | Date[] | null	True		The value of the date picker (controlled mode), supports v-model.	0.2.0
defaultValue	Date | Date[] | null	True		The default value of the date picker (uncontrolled mode).	0.2.0
mode	'date' | 'date-range' | 'year' | 'year-range' | 'month' | 'month-range' | 'quarter' | 'quarter-range' | 'week'	True	'date'	The selection mode of the date picker.	0.2.0
placeholder	string	True		Placeholder text.	0.2.0
placeholderStart	string	True		Placeholder text for the start date.	0.2.0
placeholderEnd	string	True		Placeholder text for the end date.	0.2.0
disabled	boolean	True	false	Whether it is disabled.	0.2.0
readonly	boolean	True	false	Whether it is read-only.	0.2.0
clearable	boolean	True	false	Whether to show the clear button.	0.2.0
loading	boolean	True	false	Whether to show the loading state.	0.2.0
template	string	True		Date formatting template.	0.2.0
format	(time: Date) => string	True		Date formatting function, takes precedence over template.	0.2.0
parse	(timeString: string) => Date	True		Function to parse a formatted string into a date, takes precedence over template.	0.2.0
size	'medium' | 'large' | 'small'	True	'medium'	Size of the date picker input box.	0.2.0
shape	'rect' | 'round'	True	'rect'	Shape of the date picker input box.	0.2.0
borderRadius	NumberOrPercentage | NumberOrPercentage[]	True		Border radius, higher priority than shape, consistent with CSS border-radius behavior; a single value or array of length 1 → applies to all four corners; array of length 2 → [top-left & bottom-right, top-right & bottom-left]; array of length 3 → [top-left, top-right & bottom-left, bottom-right]; array of length 4 → applies to corners in clockwise order.	0.2.0
status	'success' | 'warning' | 'error' | 'normal'	True		Form validation status.	0.2.0
autofocus	boolean	True	false	Native <input> autofocus attribute.	0.2.0
autofocusStart	boolean	True	false	Native <input> autofocus attribute for the start date.	0.2.0
autofocusEnd	boolean	True	false	Native <input> autofocus attribute for the end date.	0.2.0
dropdownDestroyOnHide	boolean	True	false	Whether the dropdown panel is destroyed when hidden.	0.2.0
pollSizeChange	boolean	True	false	Enable polling for component size changes, may affect performance.	0.2.0
dropdownProps	Omit<PopoverProps, 'visible' | 'content'> & EmitEvent<PopoverEvents>	True		Props for the dropdown panel.	0.2.0
needDropdown	boolean	True	false	Whether to show the dropdown panel.	0.2.0
quickAccess	QuickAccessOption[]	True		Options for the quick jump button.	0.2.0

DatePickerEvents

Event	Parameter	Description	Version
input	value: string, event: Event	Callback when inputting in the date picker.	0.2.0
update:modelValue	value: Date | Date[] | null	Callback for updating modelValue.	0.2.0
change	value: Date | Date[] | null, event?: Event	Callback when the date picker value changes.	0.2.0
clear	value: Date | Date[] | null	Callback when clearing the content by clicking the clear button.	0.2.0
blur	event: FocusEvent	Callback when the date picker loses focus.	0.2.0
focus	event: FocusEvent	Callback when the date picker receives focus.	0.2.0
select	value: Date | Date[], event: MouseEvent	Callback when the date picker value is changed via the dropdown panel.	0.2.0
monthPrev	referredDate: Date, event: MouseEvent	Callback when moving to the previous month in the date panel.	0.2.0
monthNext	referredDate: Date, event: MouseEvent	Callback when moving to the next month in the date panel.	0.2.0
yearPrev	referredDate: Date, event: MouseEvent	Callback when moving to the previous year in the date panel.	0.2.0
yearNext	referredDate: Date, event: MouseEvent	Callback when moving to the next year in the date panel.	0.2.0
referredDateSelect	referredDate: Date, event: MouseEvent	Callback when selecting a year/month via the dropdown options in the date panel.	0.2.0
referredDateChange	referredDate: Date, event: MouseEvent	Callback when the year/month changes in the date panel.	0.2.0
dropdownOpen		Callback when the dropdown panel is opened.	0.2.0
dropdownClose		Callback when the dropdown panel is closed.	0.2.0

DatePickerSlots

Slot	Parameter	Description	Version
prefix		Prefix content.	0.2.0
suffix		Suffix content.	0.2.0
splitter		Separator content for range selection.	0.2.0
quick	quickAccess: QuickAccessOption	The bottom slot of the dropdown panel.	0.2.0

DatePickerExpose

Attribute	Type	Optional	Default	Description	Version
focus	(placement?: 'start' | 'end') => void	False		Focus the current control; for range selection, defaults to the start date if placement is not provided.	0.2.0
blur	(placement?: 'start' | 'end') => void	False		Blur the current control; for range selection, defaults to the start date if placement is not provided.	0.2.0
clear	() => void	False		Clear the current input content.	0.2.0
select	(placement?: 'start' | 'end') => void	False		Select the current input content; for range selection, defaults to the start date if placement is not provided.	0.2.0

QuickAccessOption

export type QuickAccessOption = {
	label: string
	key?: string | number | symbol
	targetTime: Date | Date[] | (() => Date | Date[])
	buttonProps?: ButtonProps
}

NumberOrPercentage

export type NumberOrPercentage = number | `${number}%`

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}