UI Elements User Input Date/Time Picker

Updated: June 22, 2020
SAPUI5 Version 1.78

Date/Time Picker

sap.m.DateTimePicker

Intro

The date/time picker allows users to select date and time values in a combined input.

Usage

Use the date/time picker if:

  • You need a combined date and time input control.

Do not use the date time picker if:

  • You want to use either a date or a time value. In this case, use the date picker or the time picker instead.

Responsiveness

The date/time picker runs on all form factors and fully adapts to all devices.

The date/time picker opens in a popover for sizes M and L (tablet or desktop device)
The date/time picker opens in a popover for sizes M and L (tablet or desktop device)
The date/time picker opens in a dialog for size S (smartphone)
The date/time picker opens in a dialog for size S (smartphone)

Behavior and Interaction

Selecting Date and Time Values

Sizes M and L/XL

The date/time picker appears as a popover when the user clicks a date (input field) on the calendar. The user can then select the desired date from the calendar, and the time from the rotating wheel. For the time, it’s possible to select hours, minutes, and even seconds.

When the user clicks the OK button, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Date/time picker – Open
Date/time picker – Open
Date/time picker – Closed
Date/time picker – Closed

Size S and Mobile Size

On smaller devices, the user can choose the date and time value in arbitrary order by tapping the segmented button on top of the screen. Be aware that the popover is superimposed on the input field during the selection process for mobile/S sizes.

The user can select the desired date from the calendar, and the time from the rotating time wheel. For the time, it’s possible to select hours, minutes, and even seconds. Clicking a date in the calendar automatically takes the user to the time selection screen.

When the user selects OK, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Size S - Date/time picker opens with the 'Date' view
Size S - Date/time picker opens with the 'Date' view
Size S - Selecting a date opens the 'Time' view
Size S - Selecting a date opens the 'Time' view

Styles

Value States

The date/time picker supports the following value states: error, warning, success, neutral, and information. You can display a value state text for error, warning, and information states to provide hints for the user.

For more information on how to use the different semantic states, see How to Use Semantic Colors.

Error state with error value state text
Error state with error value state text
Warning state with warning value state text
Warning state with warning value state text
Information state with information value state text (for example, to indicate a recommendation)
Information state with information value state text (for example, to indicate a recommendation)

Guidelines

Date Picker and Time Picker

In general, we recommend separating the date/time picker controls as the time picker supports the mask input function and the date picker allows the user to enter date in different formats. This makes it easier and more convenient for the user to enter the desired values. For additional guidelines and information on the individual controls, see the resources section below.

Default Values

Independently of the chosen control, set the default values of the date/time picker carefully to avoid unnecessary scrolling. It often makes sense to set the default for the time to the full or half hour, setting the minutes to 00 or 30. Sometimes, it may also make sense to use the current time and date.

Formatting Dates and Times

For guidelines and information on the SAPUI5 date formatters, see formatting dates.

For guidelines and information on the SAPUI5 time formatters, see formatting times.

Setting Steps

You can set intervals for the minutes and seconds on the slider (properties: minutesStep and/or secondsStep). For example, if you set the seconds step to “5”, the slider offers “00”, “05”, “10”, “15”, and so on.

Time Zone

If the user has to set a time that is time zone-sensitive, offer a select control next to the date/time picker control to choose the appropriate time zone.

Properties

AM and PM are locale-dependent. The locale can be set using the property localeId.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation