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 valueFormat is "yyyy-MM-dd", the displayFormat is "MMM d, y", and the used locale is English, a valid value string is "2015-07-30", which leads to an output of "Jul 30, 2015". If no placeholder is set to the DatePicker, the used displayFormat is displayed as a placeholder. If another placeholder is needed, it must be set.

Relative date input

The input field also accepts locale-aware relative date expressions sourced from the Unicode CLDR. The following expressions are supported in English:

• Day: "today", "yesterday", "tomorrow"
• Week: "this week", "last week", "next week"
• Month: "this month", "last month", "next month"
• Year: "this year", "last year", "next year"

The recognized expressions are locale-specific — the equivalent terms in the user's language are used (for example, "heute" in German, "bugün" in Turkish). Week, month, and year expressions resolve to an offset from today (for example, "next week" = today + 7 days). For the full list of supported fields and patterns, see CLDR Date Fields.

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

accessibleDescription

Description	Defines the accessible description of the component.
Type	string | undefined
Default	undefined
Since	2.14.0

accessibleDescriptionRef

Description	Receives id(or many ids) of the elements that describe the input.
Type	string | undefined
Default	undefined
Since	2.14.0

accessibleName

Description	Defines the aria-label attribute for the component.
Type	string | undefined
Default	undefined
Since	1.0.0-rc.15

accessibleNameRef

Description	Receives id(or many ids) of the elements that label the component.
Type	string | undefined
Default	undefined
Since	1.0.0-rc.15

calendarWeekNumbering

Description	Defines 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" (value descriptions in: CalendarWeekNumbering)
Default	"Default"
Since	2.2.0

dateValue

Description	Currently selected date represented as a Local JavaScript Date instance. Note: this getter can only be reliably used after the component is fully defined. Use dateValueAsync which resolves only when this condition is met.
Type	Date | null
Default	null
Readonly	true
Deprecated	Use dateValueAsync instead

dateValueAsync

Description	Promise that resolves to the currently selected date represented as a Local JavaScript Date instance.
Type	Promise<Date | null>
Default	Promise
Readonly	true

disabled

Description	Determines whether the component is displayed as disabled.
Type	boolean
Default	false

displayFormat

Description	Determines the format, displayed in the input field.
Type	string | undefined
Default	undefined
Since	2.14.0

formatPattern

Description	Determines the format, displayed in the input field.
Type	string | undefined
Default	undefined
Deprecated	Use displayFormat and valueFormat instead

hideWeekNumbers

Description	Defines the visibility of the week numbers column. Note: For calendars other than Gregorian, the week numbers are not displayed regardless of what is set.
Type	boolean
Default	false
Since	1.0.0-rc.8

maxDate

Description	Determines 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).
Type	string
Default	""
Since	1.0.0-rc.6

minDate

Description	Determines 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).
Type	string
Default	""
Since	1.0.0-rc.6

name

Description	Determines 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.
Type	string | undefined
Default	undefined

open

Description	Defines the open or closed state of the popover.
Type	boolean
Default	false
Since	2.0.0

placeholder

Description	Defines 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.
Type	string | undefined
Default	undefined

primaryCalendarType

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

readonly

Description	Determines whether the component is displayed as read-only.
Type	boolean
Default	false

required

Description	Defines whether the component is required.
Type	boolean
Default	false
Since	1.0.0-rc.9

secondaryCalendarType

Description	Defines the secondary calendar type. If not set, the calendar will only show the primary calendar type.
Type	"Buddhist" | "Gregorian" | "Islamic" | "Japanese" | "Persian" | undefined
Default	undefined
Since	1.0.0-rc.16

showClearIcon

Description	Defines whether the clear icon of the input will be shown.
Type	boolean
Default	false
Since	2.20.0

value

Description	Defines a formatted date value.
Type	string
Default	""

valueFormat

Description	Determines the format, used for the value attribute.
Type	string | undefined
Default	undefined
Since	2.14.0

valueState

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

Slots

valueStateMessage

Description	Defines 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.
Type	Array<HTMLElement>
Since	1.0.0-rc.7

Events

change

Description	Fired when the input operation has finished by pressing Enter or on focusout.
Type	CustomEvent<DatePickerChangeEventDetail>
Parameters	valid: boolean Indicator if the value is in correct format pattern and in valid range. value: string The submitted value.
Bubbles	Yes
Cancelable	Yes - via preventDefault()

close

Description	Fired after the component's picker is closed.
Type	CustomEvent
Since	2.4.0
Bubbles	No
Cancelable	No

input

Description	Fired when the value of the component is changed at each key stroke.
Type	CustomEvent<DatePickerInputEventDetail>
Parameters	valid: boolean Indicator if the value is in correct format pattern and in valid range. value: string The submitted value.
Bubbles	Yes
Cancelable	Yes - via preventDefault()

open

Description	Fired after the component's picker is opened.
Type	CustomEvent
Since	2.4.0
Bubbles	No
Cancelable	No

value-state-change

Description	Fired 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.
Type	CustomEvent<DatePickerValueStateChangeEventDetail>
Parameters	valid: boolean Indicator if the value is in correct format pattern and in valid range. valueState: string The new valueState that will be set.
Bubbles	Yes
Cancelable	Yes - via preventDefault()

Methods

formatValue

Description	Formats a Java Script date object into a string representing a locale date according to the formatPattern property of the DatePicker instance
Return type	string
Parameters	date: Date A Java Script date object to be formatted as string

isInValidRange

Description	Checks if a date is between the minimum and maximum date.
Return type	boolean
Parameters	value: string A value to be checked

isValid

Description	Checks if a value is valid against the current date format of the DatePicker.
Return type	boolean
Parameters	value: string A value to be tested against the current date format
Deprecated	Use isValidValue or isValidDisplayValue instead

isValidDisplayValue

Description	Checks if a value is valid against the current date format of the DatePicker.
Return type	boolean
Parameters	value: string A value to be tested against the current date format

isValidValue

Description	Checks if a value is valid against the current date format of the DatePicker.
Return type	boolean
Parameters	value: string A value to be tested against the current date format

CSS Parts

For more information on how to use CSS shadow parts, see Usage of CSS Shadow Parts.

Name	Description
input	Used to style the input element. This part is forwarded to the underlying ui5-input element.

CSS Custom States

No CSS custom states 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.

Clear Icon

This sample demonstrates the component with the show-clear-icon property enabled, which displays a clear button to reset the selected date.