UI Elements User Input Date Range Selection

Updated: March 2, 2023
SAPUI5 Version 1.102

Date Range Selection

sap.m.DateRangeSelection

Intro

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Use the date range selection if:

  • You need a time range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should recognize the information and jump to the same selection.

Do not use the date range selection if:

  • You want to enter a date and a time. In this case, use the date picker or time picker instead.
  • The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.
  • You want to let users choose from a flexible set of absolute and relative dates and date ranges. In this case, use the dynamic date range.

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Date range selection (size S)
Date range selection (size S)
Date range selection (size L)
Date range selection (size L)

Components

The date range selection consists of two components: the date range input field (1) and the date range picker (2).

The two clickable areas of the date range selection on all devices
The two clickable areas of the date range selection on all devices

Date Range Input Field

The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

1. Current day

2. Currently selected date range

It is possible to add additional descriptive 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.

The dates December 19–22 are selected, and December 5 is shown as the current day
The dates December 19–22 are selected, and December 5 is shown as the current day

Date Range Picker

With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

1. Previous month

2. Quick month selection

3. Quick year selection

4. Next month

5. Day selection

Clickable areas of the date range selection
Clickable areas of the date range selection

Optionally, you can offer a footer with OK and Cancel buttons. This gives users an alternative way of confirming the selected date range.

Date range picker with 'OK' and 'Cancel'
Date range picker with 'OK' and 'Cancel'

Behavior and Interaction

Selecting a Date Range

The user can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

Switch View

Clicking an arrow shows the next or previous day, month, or year.

Navigating to the next month
Navigating to the next month

Clicking the month shows an overview of all months.

Opening the month picker
Opening the month picker

If the current month is clicked, the user can change the month. When the user selects a month, the view changes to the day view.

Changing the month navigates back to the date picker. The focus is on the last selected start date.
Changing the month navigates back to the date picker. The focus is on the last selected start date.

By clicking the current year, the view changes to the year view. When the user selects a year, the view changes to the day view.

Opening the year picker
Opening the year picker

Selecting a Range

After the user selects a start date, the dates being hovered over turn light blue to provide visual feedback that a range is being selected. When the user selects an end date, the calendar closes. The range appears in the date input field.

Selecting the start date
Selecting the start date
Selecting the end date
Selecting the end date

Entering Single Dates

The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

“Today” Button

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

When the user clicks the Today button, the system automatically makes the current date the starting date for the new date range.

If the user has already selected the first date in the date range and then clicks the Today button, the focus is set to the current date. The system cancels the previous selection and makes the current day the starting date for the new selection.

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

Selecting current date with the 'Today' button
Selecting current date with the 'Today' button

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Date range selection with default placeholder
Date range selection with default placeholder

Validation

Use inline validation to give the user feedback, especially for errors and warnings. Possible validation states are warning, error, success, and information. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

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

Visible frame that shows an error when the field is out of focus
Visible frame that shows an error when the field is out of focus
Error state with meaningful text; the date range input field is focused
Error state with meaningful text; the date range input field is focused
Visible frame that shows a warning when the field is out of focus
Visible frame that shows a warning when the field is out of focus
Warning state with meaningful text; the date range input field is focused
Warning state with meaningful text; the date range input field is focused
Visible frame that shows that additional information is available
Visible frame that shows that additional information is available
Information state with additional information, such as a recommendation
Information state with additional information, such as a recommendation

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Long display format
Long display format
Medium display format
Medium display format
Short display format
Short display format

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

  • Unicode CLDR short format: 14.01.14
  • Unicode CLDR medium format: 14.01.2014
  • ISO date format: 2014-01-14
  • ISO date format without delimiters: 20140114
  • Unicode CLDR short format without delimiters: 140114
  • Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for a list in a list-detail layout / object list item / title and object header / title. Here are some examples:

  • English (US): January 16, 2022
  • German (DE): 16. Januar 2022
  • Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for a list in a list-detail layout / object list item / list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

  • English (US): 1/16/22
  • German (DE): 16.01.22
  • Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for a list in a list-detail layout / object list item / list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format within table cells. Otherwise, use the medium format.

If you need to display the weekday, use the full format. For example:

  • English (US): Sunday, January 16, 2022
  • German (DE): Sonntag, 16. Januar 2022
  • French (FR): dimanche 16 janvier 2022

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