element-plus/docs/en-US/component/datetime-picker.md

title, lang

title	lang
DateTimePicker	en-US

DateTimePicker

Select date and time in one picker.

:::tip

DateTimePicker is derived from DatePicker and TimePicker. For a more detailed explanation on attributes, you can refer to DatePicker and TimePicker.

:::

Date and time

:::demo You can select date and time in one picker at the same time by setting type to datetime. The way to use shortcuts is the same as Date Picker.

datetime-picker/date-and-time

:::

DateTime Formats

Use format to control displayed text's format in the input box. Use value-format to control binding value's format.

By default, the component accepts and emits a Date object.

Check the list here of all available formats of Day.js.

:::warning

Pay attention to capitalization

:::

:::demo

datetime-picker/date-and-time-formats

:::

Date and time formats in dropdown panel

Use date-format and time-format to control displayed text's format in the dropdown panel's input box.

:::demo

datetime-picker/date-and-time-formats-panel

:::

Date and time range

:::demo You can select date and time range by setting type to datetimerange.

datetime-picker/date-and-time-range

:::

Default time value for start date and end date

:::demo When picking date range on the date panel with type datetimerange, 00:00:00 will be used as the default time value for start and end date. We can control it with the default-time attribute. default-time accepts an array of up to two Date objects. The first item controls time value of the start date and the second item controls time value of the end date.

datetime-picker/default-time

:::

Custom icon ^(2.8.0)

Custom icons available with slots.

:::demo

datetime-picker/custom-icon

:::

API

Attributes

Name	Description	Type	Default
model-value / v-model	binding value, if it is an range picker, the length of the array should be 2	^[number] / ^[string] / ^[Date] / ^[array]number[] | string[] | Date[]	''
readonly	whether DatePicker is read only	^[boolean]	false
disabled	whether DatePicker is disabled	^[boolean]	false
editable	whether the input is editable	^[boolean]	true
clearable	whether to show clear button	^[boolean]	true
size	size of Input	^[enum]'large' | 'default' | 'small'	default
placeholder	placeholder in non-range mode	^[string]	—
start-placeholder	placeholder for the start date in range mode	^[string]	—
end-placeholder	placeholder for the end date in range mode	^[string]	—
arrow-control	whether to pick time using arrow buttons	^[boolean]	false
type	type of the picker	^[enum]'year' | 'month' | 'date' | 'datetime' | 'week' | 'datetimerange' | 'daterange'	date
format	format of the displayed value in the input box	^[string] see date formats	YYYY-MM-DD HH:mm:ss
popper-class	custom class name for DateTimePicker's dropdown	^[string]	—
popper-style	custom style for DateTimePicker's dropdown	^[string] / ^[object]	—
popper-options	Customized popper option see more at popper.js	^[object]Partial<PopperOptions>	{}
fallback-placements ^(2.8.4)	list of possible positions for Tooltip popper.js	^[array]Placement[]	['bottom', 'top', 'right', 'left']
placement ^(2.8.4)	position of dropdown	Placement	bottom
range-separator	range separator	^[string]	'-'
default-value	optional, default date of the calendar	^[object]Date | [Date, Date]	—
default-time	the default time value after picking a date. Time 00:00:00 will be used if not specified	^[object]Date | [Date, Date]	—
value-format	optional, format of binding value. If not specified, the binding value will be a Date object	^[string] see date formats	—
date-format ^(2.4.0)	optional, format of the date displayed in input's inner panel	^[string] see date formats	YYYY-MM-DD
time-format ^(2.4.0)	optional, format of the time displayed in input's inner panel	^[string] see date formats	HH:mm:ss
id	same as id in native input	^[string] / ^[object][string, string]	—
name	same as name in native input	^[string]	—
unlink-panels	unlink two date-panels in range-picker	^[boolean]	false
prefix-icon	Custom prefix icon component	^[string] / Component	Date
clear-icon	Custom clear icon component	^[string] / Component	CircleClose
shortcuts	an object array to set shortcut options	^[object]Array<{ text: string, value: Date | Function }>	—
disabled-date	a function determining if a date is disabled with that date as its parameter. Should return a Boolean	^[Function](data: Date) => boolean	—
disabled-hours	To specify the array of hours that cannot be selected	^[Function](role: string, comparingDate?: Dayjs) => number[]	—
disabled-minutes	To specify the array of minutes that cannot be selected	^[Function](hour: number, role: string, comparingDate?: Dayjs) => number[]	—
disabled-seconds	To specify the array of seconds that cannot be selected	^[Function](hour: number, minute: number, role: string, comparingDate?: Dayjs) => number[]	—
cell-class-name	set custom className	^[Function](data: Date) => string	—
teleported	whether datetime-picker dropdown is teleported to the body	^[boolean]	true
empty-values ^(2.7.0)	empty values of component, see config-provider	^[array]	—
value-on-clear ^(2.7.0)	clear return value, see config-provider	^[string] / ^[number] / ^[boolean] / ^[Function]	—
show-now ^(2.8.7)	whether to show the now button	^[boolean]	true
show-footer ^(2.10.5)	whether to show footer where the date picker is one ^[enum]'datetime' | 'datetimerange'	^[boolean]	true
show-confirm ^(2.11.0)	whether to show the confirm button	^[boolean]	true
show-week-number ^(2.10.3)	show the week number besides the week	boolean	false

Events

Name	Description	Parameters
change	triggers when user confirms the value or click outside	^[Function](val: typeof v-model) => void
blur	triggers when Input blurs	^[Function](e: FocusEvent) => void
focus	triggers when Input focuses	^[Function](e: FocusEvent) => void
clear ^(2.7.7)	triggers when the clear icon is clicked in a clearable DateTimePicker	^[Function]() => void
calendar-change	triggers when the calendar selected date is changed. Only for range	^[Function](val: [Date, null | Date]) => void
panel-change	triggers when the navigation button click.	^[Function](date: Date | [Date, Date], mode: 'month' | 'year', view?: string) => void
visible-change	triggers when the DateTimePicker's dropdown appears/disappears	^[Function](visibility: boolean) => void

Slots

Name	Description
default	custom cell content
range-separator	custom range separator content
prev-month ^(2.8.0)	prev month icon
next-month ^(2.8.0)	next month icon
prev-year ^(2.8.0)	prev year icon
next-year ^(2.8.0)	next year icon

Exposes

Method	Description	Type
focus	focus the DatePicker component	^[Function]() => void
blur ^(2.8.7)	blur the DatePicker component	^[Function]() => void

Type Declarations

Show declarations

type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'