Skip to main content

DatePicker

<ui5-date-picker>

The ui5-date-picker component provides an input field with assigned calendar which opens on user action. The ui5-date-picker allows users to select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.

Usage​

The user can enter a date by:

  • Using the calendar that opens in a popup
  • Typing it in directly in the input field

When the user makes an entry and presses the enter key, the calendar shows the corresponding date. When the user directly triggers the calendar display, the actual date is displayed.

Formatting​

If a date is entered by typing it into the input field, it must fit to the used date format.

Supported format options are pattern-based on Unicode LDML Date Format notation. For more information, see UTS #35: Unicode Locale Data Markup Language.

For example, if the format-pattern is "yyyy-MM-dd", a valid value string is "2015-07-30" and the same is displayed in the input.

Keyboard Handling​

The ui5-date-picker provides advanced keyboard handling. If the ui5-date-picker is focused, you can open or close the drop-down by pressing [F4], [Alt] + [Up] or [Alt] + [Down] keys. Once the drop-down is opened, you can use the [Up], [Down], [Left] or [Right] arrow keys to navigate through the dates and select one by pressing the Space or Enter keys. Moreover you can use TAB to reach the buttons for changing month and year.

If the ui5-date-picker input field is focused and its corresponding picker dialog is not opened, then users can increment or decrement the date referenced by dateValue property by using the following shortcuts:

  • [Page Down] - Decrements the corresponding day of the month by one
  • [Shift] + [Page Down] - Decrements the corresponding month by one
  • [Shift] + [Ctrl] + [Page Down] - Decrements the corresponding year by one
  • [Page Up] - Increments the corresponding day of the month by one
  • [Shift] + [Page Up] - Increments the corresponding month by one
  • [Shift] + [Ctrl] + [Page Up] - Increments the corresponding year by one

Calendar types​

The component supports several calendar types - Gregorian, Buddhist, Islamic, Japanese and Persian. By default the Gregorian Calendar is used. In order to use the Buddhist, Islamic, Japanese or Persian calendar, you need to set the primaryCalendarType property and import one or more of the following modules:

import "@ui5/webcomponents-localization/dist/features/calendar/Buddhist.js";

import "@ui5/webcomponents-localization/dist/features/calendar/Islamic.js";

import "@ui5/webcomponents-localization/dist/features/calendar/Japanese.js";

import "@ui5/webcomponents-localization/dist/features/calendar/Persian.js";

Or, you can use the global configuration and set the calendarType key:

<script data-id="sap-ui-config" type="application/json">
	{
		"calendarType": "Japanese"
	}
<script>

ES6 Module Import​

import "@ui5/webcomponents/dist/DatePicker.js";

Basic Sample​

Properties​

value​

DescriptionDefines a formatted date value.
Typestring
Default""

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Positive" | "Critical" | "Negative" | "Information"
Default"None"

required​

DescriptionDefines whether the component is required.
Typeboolean
Defaultfalse
Since1.0.0-rc.9

disabled​

DescriptionDetermines whether the component is displayed as disabled.
Typeboolean
Defaultfalse

readonly​

DescriptionDetermines whether the component is displayed as read-only.
Typeboolean
Defaultfalse

placeholder​

DescriptionDefines a short hint, intended to aid the user with data entry when the component has no value.
Note: When no placeholder is set, the format pattern is displayed as a placeholder. Passing an empty string as the value of this property will make the component appear empty - without placeholder or format pattern.
Typestring | undefined
Defaultundefined

name​

DescriptionDetermines the name by which the component will be identified upon submission in an HTML form.
Note: This property is only applicable within the context of an HTML Form element.
Typestring | undefined
Defaultundefined

hideWeekNumbers​

DescriptionDefines the visibility of the week numbers column.
Note: For calendars other than Gregorian, the week numbers are not displayed regardless of what is set.
Typeboolean
Defaultfalse
Since1.0.0-rc.8

open​

DescriptionDefines the open or closed state of the popover.
Typeboolean
Defaultfalse
Since2.0.0

accessibleName​

DescriptionDefines the aria-label attribute for the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleDescription​

DescriptionDefines the accessible description of the component.
Typestring | undefined
Defaultundefined
Since2.14.0

accessibleDescriptionRef​

DescriptionReceives id(or many ids) of the elements that describe the input.
Typestring | undefined
Defaultundefined
Since2.14.0

dateValue​

DescriptionCurrently selected date represented as a Local JavaScript Date instance.
TypeDate | null
Defaultnull
Readonlytrue

primaryCalendarType​

DescriptionSets a calendar type used for display. If not set, the calendar type of the global configuration is used.
Type"Gregorian" | "Islamic" | "Japanese" | "Buddhist" | "Persian" | undefined
Defaultundefined

secondaryCalendarType​

DescriptionDefines the secondary calendar type. If not set, the calendar will only show the primary calendar type.
Type"Gregorian" | "Islamic" | "Japanese" | "Buddhist" | "Persian" | undefined
Defaultundefined
Since1.0.0-rc.16

formatPattern​

DescriptionDetermines the format, displayed in the input field.
Typestring | undefined
Defaultundefined
DeprecatedUse displayFormat and valueFormat instead

displayFormat​

DescriptionDetermines the format, displayed in the input field.
Typestring | undefined
Defaultundefined
Since2.14.0

valueFormat​

DescriptionDetermines the format, used for the value attribute.
Typestring | undefined
Defaultundefined
Since2.14.0

minDate​

DescriptionDetermines the minimum date available for selection.
Note: If the formatPattern property is not set, the minDate value must be provided in the ISO date format (yyyy-MM-dd).
Typestring
Default""
Since1.0.0-rc.6

maxDate​

DescriptionDetermines the maximum date available for selection.
Note: If the formatPattern property is not set, the maxDate value must be provided in the ISO date format (yyyy-MM-dd).
Typestring
Default""
Since1.0.0-rc.6

calendarWeekNumbering​

DescriptionDefines how to calculate calendar weeks and first day of the week. If not set, the calendar will be displayed according to the currently set global configuration.
Type"Default" | "ISO_8601" | "MiddleEastern" | "WesternTraditional"
Default"Default"
Since2.2.0

Slots​

valueStateMessage​

DescriptionDefines the value state message that will be displayed as pop up under the component.
Note: If not specified, a default text (in the respective language) will be displayed.
Note: The valueStateMessage would be displayed, when the component is in Information, Critical or Negative value state.
TypeArray<HTMLElement>
Since1.0.0-rc.7

Events​

change​

DescriptionFired when the input operation has finished by pressing Enter or on focusout.
TypeCustomEvent<DatePickerChangeEventDetail>
Parametersvalue: string
The submitted value.
valid: boolean
Indicator if the value is in correct format pattern and in valid range.
BubblesYes
CancelableYes - via preventDefault()

input​

DescriptionFired when the value of the component is changed at each key stroke.
TypeCustomEvent<DatePickerInputEventDetail>
Parametersvalue: string
The submitted value.
valid: boolean
Indicator if the value is in correct format pattern and in valid range.
BubblesYes
CancelableYes - via preventDefault()

value-state-change​

DescriptionFired before the value state of the component is updated internally. The event is preventable, meaning that if it's default action is prevented, the component will not update the value state.
TypeCustomEvent<DatePickerValueStateChangeEventDetail>
ParametersvalueState: string
The new valueState that will be set.
valid: boolean
Indicator if the value is in correct format pattern and in valid range.
BubblesYes
CancelableYes - via preventDefault()

open​

DescriptionFired after the component's picker is opened.
TypeCustomEvent
Since2.4.0
BubblesNo
CancelableNo

close​

DescriptionFired after the component's picker is closed.
TypeCustomEvent
Since2.4.0
BubblesNo
CancelableNo

Methods​

isValid​

DescriptionChecks if a value is valid against the current date format of the DatePicker.
Return typeboolean
Parametersvalue: string
A value to be tested against the current date format
DeprecatedUse isValidValue or isValidDisplayValue instead

isValidValue​

DescriptionChecks if a value is valid against the current date format of the DatePicker.
Return typeboolean
Parametersvalue: string
A value to be tested against the current date format

isValidDisplayValue​

DescriptionChecks if a value is valid against the current date format of the DatePicker.
Return typeboolean
Parametersvalue: string
A value to be tested against the current date format

isInValidRange​

DescriptionChecks if a date is between the minimum and maximum date.
Return typeboolean
Parametersvalue: string
A value to be checked

formatValue​

DescriptionFormats a Java Script date object into a string representing a locale date according to the formatPattern property of the DatePicker instance
Return typestring
Parametersdate: Date
A Java Script date object to be formatted as string

CSS Parts​

No CSS parts available for this component.

More Samples​

States​

Min and Max Dates​

Define min and max date boundaries to contrain user choice.

Calendar Types​

You can set the preferred calendar, such as: Gregorian, Islamic, Japanese and Persian.

Timezones​

You can set to the configuration the preferred time zone, such as: Asia/Tokyo, Pacific/Apia, Asia/Kolkata, Europe/Sofia and etc.

CalendarWeekNumbering​

You can use the component, the preferred week numbering and first day of week.

CustomFormatting​

You can have custom formatting for the display value and the value property. Supported format options are pattern-based on Unicode LDML Date Format notation. For more information, see UTS #35: Unicode Locale Data Markup Language.