🌏 Translated with the assistance of DeepSeek and ChatGPT

TimePicker

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

Range Selection

Hide source code

Quick Access

Single Value

Range

24 Hours

12 Hours

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

TimePicker 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

TimePickerProps

Attribute	Type	Optional	Default	Description	Version
modelValue	Date | Date[] | null	True		The value of the time picker (controlled mode), supports v-model.	0.2.0
defaultValue	Date | Date[] | null	True		The default value of the time picker (uncontrolled mode).	0.2.0
mode	'time' | 'time-range'	True	'time'	The mode of date selection.	0.2.0
use12Hours	boolean	True	false		0.2.0
placeholder	string	True		Placeholder text.	0.2.0
placeholderStart	string	True		Placeholder text for the start time.	0.2.0
placeholderEnd	string	True		Placeholder text for the end time.	0.2.0
disabled	boolean	True	false	Whether to disable.	0.2.0
readonly	boolean	True	false	Whether to be 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 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 formatted string into a date, takes precedence over template.	0.2.0
size	'medium' | 'large' | 'small'	True	'medium'	Size of the time picker input box.	0.2.0
shape	'rect' | 'round'	True	'rect'	Shape of the time picker input box.	0.2.0
borderRadius	NumberOrPercentage | NumberOrPercentage[]	True		Border radius, higher priority than shape, consistent with CSS border-radius behavior; single value or array of length 1 → 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 clockwise.	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	Whether to poll for component size changes (may affect performance).	0.2.0
dropdownProps	Omit<PopoverProps, 'visible' | 'content'> & EmitEvent<PopoverEvents>	True		Properties 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

TimePickerEvents

Event	Parameter	Description	Version
input	value: string, event: Event	Callback when the time picker input is triggered.	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 time picker value changes.	0.2.0
clear	value: Date | Date[] | null	Callback when the clear text button is clicked and content is cleared.	0.2.0
blur	event: FocusEvent	Callback when the time picker loses focus.	0.2.0
focus	event: FocusEvent	Callback when the time picker gains focus.	0.2.0
select	value: Date | Date[], event: Event	Callback when the time picker value is changed via the dropdown 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

TimePickerSlots

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

TimePickerExpose

Attribute	Type	Optional	Default	Description	Version
focus	(placement?: 'start' | 'end') => void	False		Focuses the current control; for range selection, defaults to the start time if placement is not provided.	0.2.0
blur	(placement?: 'start' | 'end') => void	False		Blurs the current control; for range selection, defaults to the start time if placement is not provided.	0.2.0
clear	() => void	False		Clears the current input content.	0.2.0
select	(placement?: 'start' | 'end') => void	False		Selects the current input content; for range selection, defaults to the start time 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
}