Intro

The date picker lets users select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.

Use this control if the user needs to enter a single date or a date range. The control also allows users to navigate directly from one month or year to another.

Usage

Use the date picker if:

Responsiveness

The date picker provides responsive behavior that allows for simple operation on all devices. It is smaller in compact mode and provides a touch-friendly size in cozy mode.

Clicking the date picker button opens the popover in full screen. To close it, the user can select a date (which triggers the close event), or click Cancel without selecting a date. Clicking the date input field allows the user to type and does not open the date picker popover.

Date picker on a smartphone

Date picker on a desktop

Date picker on a desktop

Components

The date picker has two components: the date input field and the date picker button. On all devices users can either use the input field to type a date or use the date picker button to open the date picker calendar.

Date picker with input field and button

Date picker with input field and button

Date Input Field

In the input field, the user can enter a date directly or select it using the date picker. The system validates the entry and provides the user with feedback. You can also show placeholder text in the field.

Date Picker

With the date picker, the user can see a day view, month view, year view, or year ranges.

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 navigate to the previous and the next day, month, or year view, depending on the current view.

The selected date is shown with a blue background. The current day is indicated with a purple border and owns the focus.

Date picker with a selected date and the current date

Date picker with a selected date and the current date

Clickable areas of the date picker

Clickable areas of the date picker

You can change the default focus “today” to another date. This can save users several clicks when they create events. For an event end date, for example, the focus should propose a date in the future (after the start date).

Use case-specific focus date

Use case-specific focus date

Month and Year Views

The month and year views can be used separately in a month or year picker. The year ranges are related to the year view and are not used separately. Selecting a year range navigates back to the year view, not the day view.

Month view in the date picker

Month view in the date picker

Year view in the date picker

Year view in the date picker

Year ranges in the date picker

You can add a footer with OK and Cancel buttons to the date picker popover. However, we advise against this unless it’s very important that the user can pick multiple values (day, month, year) without closing the popover.

The default and recommended behavior is to close the date picker popover upon selection of the day (or month/year for the month and year pickers).

Date picker with footer

Behavior and Interaction

Selecting a Date

The user selects a date by clicking the date. After the user selects a day, the calendar closes and the date appears in the date input field.
Date selection
Clicking the arrow shows the next day, month, or year view.
Navigating to the next month
If the current month is clicked, the view changes to the month view and the user can change the month.
Switching to month view
By clicking on a month, the user changes the month and the view changes to the day view.

Selecting another month

Selecting another month

The user can similarly change the year. By clicking the current year, the view changes to the year view. After the user selects a year, the view changes back to the day view.

Switching to year view

Switching to year view

After the user selects a year, the view changes back to the day view. The date in the date input field stays the same until the user selects a new date.

Selecting another year

Selecting another year

Styles

Value States

The date 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 Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

Short Date Format

Use the short date format for master list/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:

Relative and Medium Date Format

If appropriate, use a relative format for master list/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 in table cells. Otherwise use the medium format.

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

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

Visual Design