docs_vue2/one/docs/en-US/components/date-picker.md

DatePicker

Demos

Selecting a single date

By default, you can click a date cell in the dropdown overlay to select a single date. Use the clearable prop to make selected values clearable. Use the placeholder prop to customize the description text displayed when nothing is selected yet.

Selecting a date range

When range is true, you can select a date range in the dropdown overlay.

Setting selection shortcuts

When selecting a date range, the shortcuts prop can be used to provide predefined date range shortcuts to be selected from.

API

Props

Name	Type	Default	Description
range	boolean=	false	Whether users can select a date range. When the value is not 'date', range will be ignored.
selected	`Date	Array=`	-
panel	number=	1	The number of month panel displayed in the dropdown overlay.
today	Date=	new Date()	The date of “today”.
week-start	number=	calendar.weekStart	The start of a week. Can be globally configured.
fill-month	boolean=	true	Whether to show dates of previous and next month in current panel when there's only one month panel.
date-class	`string	Array	Object
disabled-date	function(Date, Date=): boolean=	() => false	Used to customize whether the specified date is disabled or not. The first parameter is the date to be used to determine if the date is disabled. When in the range selection process and a date is already selected, it is passed as the second parameter.
clearable	boolean=	false	Whether selected date (ranges) can be cleared.
placeholder	string=	range ? datepicker.rangePlaceholder : datepicker.placeholder	The placeholder text displayed when nothing is selected. Can be globally configured.
format	`string	function(Date): string=`	'YYYY-MM-DD'
parse	function(string): Date=	Custom function to parse the input string expressions into Date objects.
shortcuts	Array<Object>=	datepicker.shortcuts	[^shortcuts]
shortcuts-position	string=	datepicker.shortcutsPosition	The position of shortcuts. Can be either 'before' or 'after', corresponding to the before or after the content of the month panel respectively. Can be globally configured.
expanded	boolean=	false	[^expanded]
disabled	boolean=	false	Whether the date picker is disabled.
readonly	boolean=	false	Whether the date picker is read-only.

^^^selected :::badges v-model :::

The selected date (range). Value type is determined by whether range is true.

+++Value types

range	Type
false	Date
true	[Date, Date]
+++
^^^

^^^shortcuts Selection shortcuts can be custmized when selecting a date range. The data type is Array<{label, from, to}>. Can be globally configured.

+++Properties

Name	Type	Description
label	string	Text displayed for the shortcut option.
from	Denotes the start date of the shortcut option. See more at Date offset format for shortcut option below.
to	Denotes the end date of the shortcut option. See more at Date offset format for shortcut option below.

+++ ^^^

Date offset format for shortcut option

The from and to property in shortcuts options, which are used to calculate the start/end date of an shortcut option, share the same format which is number|Object and default to 0.

• number values are the offset in days calculated against “today”. eg. -1 means { startOf: 'day', days: -1 }, which is “yesterday”.

• Object values have the type of {startOf: string=, days: number=, weeks: number=, months: number=, }.

  +++Properties

  Name	Type	Default	Description
  startOf	string=	'day'	The base date. Supported values include 'day'/'week'/'month'/'quarter'/'year'.
  day	number=	-	Offset in days.
  week	number=	-	Offset in weeks.
  month	number=	-	Offset in months.
  quarter	number=	-	Offset in quarters.
  year	number=	-	Offset in years.

The final date is calculated by accumulating the offset onto the base date.

The following example with labels may help to better understand the calculation logic. You can rapidly set shortcut options once you understand the underlying logic.

[
  {
    label: 'Last month',
    // Turn back a month from the first day of current month,
    // which is the first day of last month
    from: {
      startOf: 'month',
      month: -1
    },
    // Turn back a day from the first day of current month,
    // which is the last day of last month
    to: {
      startOf: 'month',
      days: -1
    }
  },
  {
    label: 'This month',
    // The first day of current month
    from: {
      startOf: 'month'
    },
    // Today
    to: 0
  },
  {
    label: 'This week',
    // The first day of the week, days being 0 can be omitted
    from: {
      startOf: 'week',
      days: 0
    },
    // Today
    to: 0
  },
  {
    label: 'Last 7 days',
    // Turn back 6 days backward from today
    from: -6,
    // To today
    to: 0
  },
  {
    label: 'Today',
    to: 0
  }
]

^^^expanded :::badges .sync :::

Whether the dropdown overlay is expanded. ^^^

Slots

Name	Description
date	[^scoped-slot-date]

^^^scoped-slot-date The content of each date cell in the dropdown overlay. Displays the corresponding day of month by default.

+++Scope properties

Name	Type	Description
year	number	The full representation of year.
month	number	Month of a year, starting from 0 as January.
date	number	The day of month.
+++
^^^

Events

Name	Description
select	[^event-select]
selectstart	Triggered when selecting a date range and a start date is selected. The callback parameter list is (picking: Date), being the selected start date.
selectprogress	[^event-selectprogress]
toggle	Triggered when the expanded state is going to change. The callback parameter list is (expanded: boolean). expanded denotes whether the dropdown overlay is to be expanded or collapsed.

^^^event-select :::badges v-model :::

Triggered when the selected date (range) is changed. The callback parameter list is (selected) with selected having the same type with the selected prop. ^^^

^^^event-selectprogress Triggered when selecting a date range and an end date is marked with pointer/keyboard interaction, and for each time the end date changes. The callback parameter list is (picking), with picking being the marked date range. The type of picking depends on the value of the multiple prop.

+++Parameters types

multiple	Type
false	[Date, Date]
true	Array<[Date, Date]>
+++
^^^

Global config

Key	Type	Default	Description
datepicker.shortcuts	Array	[]	Default shortcut options.
datepicker.shortcutsPosition	string	'before'	Shows the shortcut options before or after month panels. Corresponds to 'before' and 'after' respectively.
datepicker.placeholder	string	@@datepicker.selectDate	Placeholder text displayed when selecting a single date.
datepicker.monthPlaceholder	string	@@datepicker.selectMonth	Placeholder text displayed when selecting a month.
datepicker.yearPlaceholder	string	@@datepicker.selectYear	Placeholder text displayed when selecting a year.
datepicker.rangePlaceholder	string	@@datepicker.selectRange	Placeholder text displayed when selecting a date range.

:::tip @@ prefixed values denote corresponding properties in the locale settings. :::

Icons

Name	Description
calendar	Calendar.
clear	Clear selection.