DatePicker

Use Date Picker for date input.

Enter Date

Basic date picker measured by 'day'.

The measurement is determined by the type attribute. You can enable quick options via shortcuts property. The disabled date is set by disabledDate, which is a function.

Default
Picker with quick options

Other measurements

You can choose week, month, year or multiple dates by extending the standard date picker component.

Week
Dates
Year
Years
Month
Months

Date Range

Picking a date range is supported.

When in range mode, the left and right panels are linked by default. If you want the two panels to switch current months independently, you can use the unlink-panels attribute.

Default
With quick options

Month Range

Picking a month range is supported.

When in range mode, the left and right panels are linked by default. If you want the two panels to switch current years independently, you can use the unlink-panels attribute.

Default
With quick options

Year Range 2.8.0

Picking a year range is supported.

When in range mode, the left and right panels are linked by default. If you want the two panels to switch years independently, you can use the unlink-panels attribute.

Default
With quick options

Default Value

If user hasn't picked a date, shows today's calendar by default. You can use default-value to set another date. Its value should be parsable by new Date().

If type is daterange, default-value sets the left side calendar.

date
daterange

Date 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

Emits Date object
Value:
Use value-format
Value:
Timestamp
Value:

Default time for start date and end date

When picking a date range, you can assign the time part for start date and end date.

By default, the time part of start date and end date are both 00:00:00. Setting default-time can change their time respectively. It accepts an array of up to two Date objects. The first string sets the time for the start date, and the second for the end date.

Component value:

Set custom content of prefix

The content of prefix can be customized.

Setting prefix-icon to component which you import form other .vue or generated by the render function.

set prefix-icon

Custom content

The content of cell can be customized, in scoped-slot you can get the cell data. Note that the custom content structure should be consistent with the default structure, otherwise style misalignment may occur.

Custom icon 2.8.0

Custom icons available with slots.

date
date range
month range
year range

For data details, please refer:

ts
interface DateCell {
  column: number
  customClass: string
  disabled: boolean
  end: boolean
  inRange: boolean
  row: number
  selected: Dayjs
  isCurrent: boolean
  isSelected: boolean
  start: boolean
  text: number
  timestamp: number
  date: Date
  dayjs: Dayjs
  type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}

Localization

The default locale of is English, if you need to use other languages, please check Internationalization

Note, date time locale (month name, first day of the week ...) are also configured in localization.

API

Attributes

Name Description Type Default
model-value / v-model binding value, if it is an array, the length should be 2 number / string / object ''
readonly whether DatePicker is read only boolean false
disabled whether DatePicker is disabled boolean false
size size of Input enum
editable whether the input is editable boolean true
clearable whether to show clear button boolean true
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
type type of the picker enum date
format format of the displayed value in the input box string see date formats YYYY-MM-DD
popper-class custom class name for DatePicker's dropdown string
popper-options Customized popper option see more at popper.js object {}
range-separator range separator string '-'
default-value optional, default date of the calendar object
default-time optional, the time value to use when selecting date range object
value-format optional, format of binding value. If not specified, the binding value will be a Date object string see date formats
id same as id in native input string / object
name same as name in native input string / object ''
unlink-panels unlink two date-panels in range-picker boolean false
prefix-icon custom prefix icon component. By default, if the value of type is TimeLikeType, the value is Clock, else is Calendar string / object ''
clear-icon custom clear icon component string / object CircleClose
validate-event whether to trigger form validation boolean true
disabled-date a function determining if a date is disabled with that date as its parameter. Should return a Boolean Function
shortcuts an object array to set shortcut options object []
cell-class-name set custom className Function
teleported whether date-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
fallback-placements 2.8.4 list of possible positions for Tooltip popper.js arrary
placement 2.8.4 position of dropdown Placement bottom

Events

Name Description Type
change triggers when user confirms the value Function
blur triggers when Input blurs Function
focus triggers when Input focuses Function
clear 2.7.7 triggers when the clear icon is clicked in a clearable DatePicker Function
calendar-change triggers when the calendar selected date is changed. Function
panel-change triggers when the navigation button click. Function
visible-change triggers when the DatePicker's dropdown appears/disappears Function

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

Name Description Type
focus focus the Input component Function
handleOpen 2.2.16 open the DatePicker popper Function
handleClose 2.2.16 close the DatePicker popper Function

Type Declarations

Show declarations
ts
import type { Options as PopperOptions } from '@popperjs/core'

type TimeLikeType = 'datetime' | 'datetimerange'

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

Source

Component Style Docs

Contributors