DatePicker

Use Date Picker for date input.

TIP

This component requires the <client-only></client-only> wrap when used in SSR (eg: Nuxt) and SSG (eg: VitePress).

Enter Date

Basic date picker measured by 'day'.

Other measurements

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

Date Range

Picking a date range is supported.

Month Range

Picking a month range is supported.

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 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

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.

Set custom content of prefix

The content of prefix can be customized.

Custom content

The content of cell can be customized, in scoped-slot you can get the cell data.

For data details, please refer:

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

NameDescriptionTypeDefault
model-value / v-modelbinding value, if it is an array, the length should be 2number / string / object''
readonlywhether DatePicker is read onlybooleanfalse
disabledwhether DatePicker is disabledbooleanfalse
sizesize of Inputenum
editablewhether the input is editablebooleantrue
clearablewhether to show clear buttonbooleantrue
placeholderplaceholder in non-range modestring''
start-placeholderplaceholder for the start date in range modestring
end-placeholderplaceholder for the end date in range modestring
typetype of the pickerenumdate
formatformat of the displayed value in the input boxstring see date formatsYYYY-MM-DD
popper-classcustom class name for DatePicker's dropdownstring
popper-optionsCustomized popper option see more at popper.jsobject{}
range-separatorrange separatorstring'-'
default-valueoptional, default date of the calendarobject
default-timeoptional, the time value to use when selecting date rangeobject
value-formatoptional, format of binding value. If not specified, the binding value will be a Date objectstring see date formats
idsame as id in native inputstring / object
namesame as name in native inputstring / object''
unlink-panelsunlink two date-panels in range-pickerbooleanfalse
prefix-iconcustom prefix icon component. By default, if the value of type is TimeLikeType, the value is Clock, else is Calendarstring / object''
clear-iconcustom clear icon componentstring / objectCircleClose
validate-eventwhether to trigger form validationbooleantrue
disabled-datea function determining if a date is disabled with that date as its parameter. Should return a BooleanFunction
shortcutsan object array to set shortcut optionsobject[]
cell-class-nameset custom classNameFunction
teleportedwhether date-picker dropdown is teleported to the bodybooleantrue
empty-values 2.7.0empty values of component, see config-providerarray
value-on-clear 2.7.0clear return value, see config-providerstring / number / boolean / Function

Events

NameDescriptionType
changetriggers when user confirms the valueFunction
blurtriggers when Input blursFunction
focustriggers when Input focusesFunction
calendar-changetriggers when the calendar selected date is changed.Function
panel-changetriggers when the navigation button click.Function
visible-changetriggers when the DatePicker's dropdown appears/disappearsFunction

Slots

NameDescription
defaultcustom cell content
range-separatorcustom range separator content

Exposes

NameDescriptionType
focusfocus the Input componentFunction
handleOpen 2.2.16open the DatePicker popperFunction
handleClose 2.2.16close the DatePicker popperFunction

Type Declarations

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

type TimeLikeType = 'datetime' | 'datetimerange'

Source

ComponentDocs

Contributors