Intro

The date/time picker allows users to select date and time values in a combined input. It combines a calendar view with time selection in a single field, supporting both compact and cozy display modes.

Date/time picker showing both date and time in the input field

When to Use

Anatomy

Data/time picker anatomy

1. Date input field: The container in which users enter date and time. Includes a mask to guide input formatting.
2. Date time button: The button which opens the date time selection dialog.
3. Time picker: Allows users to select a time using a localized clock interface.
4. Dialog footer: Contains the OK and Cancel buttons for confirming or discarding input.
5. Date Picker: Displays a calendar for selecting the date.

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 the date/time icon in the input field. 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 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.

If there is no value in the input field, no date is selected in the calendar. The user needs to explicitly select a date. If a date is already selected and the user changes the year or the month, they need to explicitly select the date again to confirm the change.

Date/time picker – entering a value manually or by opening the popover to pick a date and time.

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.

Date/time picker - smartphone view showing segmented controls for switching between date and time selection.

“Today” Button

You can offer a shortcut for navigating to the current date (sap.m.DateTimePicker, property: showCurrentDateButton). This displays an additional Today icon button (:icon-appointment ) in the navigation part of the calendar. Pressing this button sets the focus to the current date.

This feature is available for pickers that enable selection of individual days. For the others, the property has no effect.

“Today” button in the calendar navigation lets users quickly jump to the current date.

States

The date/time picker combines date and time selection and supports both interaction states and value states. Interaction states include default, hover, active, focused, and disabled offering visual cues for user input. Value states - success, warning, error, and information. These states offer validation feedback to confirm correct or incorrect entries. The combination of interaction and value states reflects the current status of the field and guides user input.

For the Warning, Error and Information states, there are additional messages available to provide hints for the user.

For more information, see How to Use Semantic Colors.

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 individual controls, see the Related Links 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.

Date Input Field

It is possible to add additional “description” texts to the input field (a unit of measurement, for example) by using a new association in the sap.m.InputBase control called ariaDescribedBy. The association is responsible for referencing the elements that describe the control.

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.

Related Links