Skip to main content

DateTimePicker

The DateTimePicker component alows users to select both date (day, month and year) and time (hours, minutes and seconds) and for the purpose it consists of input field and Date/Time picker.

Usage​

Use the DateTimePicker if you need a combined date and time input component. Don't use it if you want to use either date, or time value. In this case, use the DatePicker or the TimePicker components instead.

The user can set date/time by:

  • using the calendar and the time selectors
  • typing in the input field

Programmatically, to set date/time for the DateTimePicker, use the value property

Formatting​

The value entered by typing into the input field must fit to the used date/time format.

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

Example: the following format dd/MM/yyyy, hh:mm:ss aa corresponds the 13/04/2020, 03:16:16 AM value.

The small 'h' defines "12" hours format and the "aa" symbols - "AM/PM" time periods.

Example: the following format dd/MM/yyyy, HH:mm:ss corresponds the 13/04/2020, 15:16:16 value.

The capital 'H' indicates "24" hours format.

Note: If the formatPattern does NOT include time, the DateTimePicker will fallback to the default time format according to the locale.

Note: If no placeholder is set to the DateTimePicker, the current formatPattern is displayed as a placeholder. If another placeholder is needed, it must be set or in case no placeholder is needed - it can be set to an empty string.

Note: If the user input does NOT match the formatPattern, the DateTimePicker makes an attempt to parse it based on the locale settings.

Responsive behavior​

The DateTimePicker is responsive and fully adapts to all devices. For larger screens, such as tablet or desktop, it is displayed as a popover, while on phone devices, it is displayed full screen.

ES6 Module Import​

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

Basic Sample​

Properties​

value​

DescriptionDefines a formatted date value.
Typestring
Default""

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Success" | "Warning" | "Error" | "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 with which the component will be submitted in an HTML form.
Important: For the name property to have effect, you must add the following import to your project: import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";
Note: When set, a native input HTML element will be created inside the component so that it can be submitted as part of an HTML form. Do not use this property unless you need to submit a form.
Typestring
Default""

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

accessibleName​

DescriptionDefines the aria-label attribute for the component.
Typestring
Default""
Since1.0.0-rc.15

accessibleNameRef​

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

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

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

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, Warning or Error 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.

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.

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.

Methods​

openPicker​

DescriptionOpens the picker.
Return typePromise<void>

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

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

closePicker​

DescriptionCloses the picker.
Return typevoid

isOpen​

DescriptionChecks if the picker is open.
Return typeboolean

CSS Parts​

No CSS parts available for this component.

More Samples​

Date-Time Formats​

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

Min and Max Dates​

Define min and max date-time boundaries to contrain user choice.