UI5 Web Components
Search

DateTimePicker

v1.0.0-rc.7
@ui5/webcomponents
<ui5-datetime-picker>

DateTimePicker

<ui5-datetime-picker></ui5-datetime-picker>

DateTimePicker with format-pattern

d/MM/yyyy, hh:mm aa
yyyy-MM-dd-hh:mm:ss aa
d/MM/yyyy, hh:mm:ss aa 
<ui5-datetime-picker
	format-pattern="dd/MM/yyyy, hh:mm aa"
	value="13/04/2020, 09:16 AM"
></ui5-datetime-picker>

<ui5-datetime-picker
	format-pattern="yyyy-MM-dd-hh:mm:ss aa"
	value="2020-04-13-04:16:16 AM"
></ui5-datetime-picker>

<ui5-datetime-picker
	id="myDateTimePicker"
	format-pattern="dd/MM/yyyy, hh:mm:ss aa"
	value="13/04/2020, 03:16:16 AM"
></ui5-datetime-picker>

<script>
	myDateTimePicker.addEventListener("change", event => {});
</script>

DateTimePicker in states



<ui5-datetime-picker value-state="Error"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Warning"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Information"></ui5-datetime-picker>
<ui5-datetime-picker value-state="Success"></ui5-datetime-picker>
<ui5-datetime-picker readonly value="2020-04-13-04:16:16 AM"></ui5-datetime-picker>
<ui5-datetime-picker disabled value="2020-04-13-04:16:16 AM"></ui5-datetime-picker>

DateTimePicker with secondary calendar type

<ui5-datetime-picker
	primary-calendar-type="Gregorian"
	secondary-calendar-type="Islamic"
></ui5-datetime-picker>

Overview

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

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
""
Defines the aria-label attribute for the component.
since v1.0.0-rc.15
accessibleNameRef
accessible-name-ref
string
""
Receives id(or many ids) of the elements that label the component.
since v1.0.0-rc.15
dateValue (readonly)
date-value
Date
Currently selected date represented as a Local JavaScript Date instance.
disabled
boolean
false
Determines whether the component is displayed as disabled.
hideWeekNumbers
hide-week-numbers
boolean
false
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.
since v1.0.0-rc.8
name
string
""
Determines 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.
placeholder
string
undefined
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.
readonly
boolean
false
Determines whether the component is displayed as read-only.
required
boolean
false
Defines whether the component is required.
since v1.0.0-rc.9
value
string
""
Defines a formatted date value.
valueState
value-state
ValueState
"None"
Defines the value state of the component.

Available options are:
  • None
  • Error
  • Warning
  • Success
  • Information
formatPattern
format-pattern
string
""
Determines the format, displayed in the input field.
maxDate
max-date
string
""
Determines the maximum date available for selection.
since v1.0.0-rc.6
minDate
min-date
string
""
Determines the minimum date available for selection.
since v1.0.0-rc.6
primaryCalendarType
primary-calendar-type
CalendarType
Sets a calendar type used for display. If not set, the calendar type of the global configuration is used.
secondaryCalendarType
secondary-calendar-type
CalendarType
undefined
Defines the secondary calendar type. If not set, the calendar will only show the primary calendar type.
since v1.0.0-rc.16

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
valueStateMessage
HTMLElement
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, Warning or Error value state.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
change
Fired when the input operation has finished by pressing Enter or on focusout.
value
type: string
description: The submitted value.
valid
type: boolean
description: Indicator if the value is in correct format pattern and in valid range.
input
Fired when the value of the component is changed at each key stroke.
value
type: string
description: The submitted value.
valid
type: boolean
description: Indicator if the value is in correct format pattern and in valid range.

Methods

This Web Component exposes public methods. You can invoke them directly on the Web Component instance.

Name
Description
closePicker
Closes the picker.
formatValue
Formats a Java Script date object into a string representing a locale date according to the formatPattern property of the DatePicker instance
date
type: object
description: A Java Script date object to be formatted as string
isInValidRange
Checks if a date is between the minimum and maximum date.
value
type: string
description: A value to be checked
isOpen
Checks if the picker is open.
isValid
Checks if a value is valid against the current date format of the DatePicker.
value
type: string
description: A value to be tested against the current date format
openPicker
Opens the picker.
Theme: Morning Horizon (Light) Evening Horizon (Dark) Horizon High Contrast Black Horizon High Contrast White Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel