This guideline now covers both SAPUI5 and SAP Web Components. Learn more.
Information
Icon
false

Intro

The date picker is a UI component used to select a single date using touch, mouse, or keyboard input. It supports manual entry in the input field and calendar-based selection via the date picker button.

Date picker

Component availability

This component is available in the following libraries:

<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.m.DatePicker">sap.m.DatePicker</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FDatePicker%2F">ui5-date-picker</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fdesign%2FSILcWzK5uFghKun9jx6D7c%2FSAP-Web-UI-Kit%3Fnode-id%3D165167-1225">Date (Range) Picker</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>
<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.m.DatePicker">sap.m.DatePicker</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FDatePicker%2F">ui5-date-picker</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Fiori for Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1494295794601744471">Date Picker</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the date picker to:

  • Let users select a single date.
  • Let users navigate directly from one month or year to another.
dont
false

Don’t use the date picker to:

  • Provide a combined date and time input component. In this case, use the date/time picker.
  • Keep the calendar visible and prominent or offer multiple days selection. Use the calendar instead.
  • Enter a date range. Use the date range selection instead.
  • Support direct date entry by typing the value in the input field.
  • Choose the appropriate date picker type (date, month, or year) depending on the required level of granularity.
  • Use value-state messages to provide meaningful and actionable feedback.
  • Define minimum and maximum dates when business rules apply to prevent invalid input at the source.
  • Use placeholders to clearly indicate the expected date format.
  • Use an icon button, text button, or a link to trigger the opening of the popover when you need to hide the input field.
  • Provide tooltips on the date picker button and the calendar to improve clarity and usability.
  • Offer a “current date” shortcut to help users return quickly to the present moment.
  • Enable special dates with a legend to highlight important days, such as holidays or events.
  • Add a footer with OK and Cancel buttons when you need users to explicitly confirm the date selection.
  • Use mixed calendar views only when users need to compare or work across different calendar systems.
  • Apply the appropriate content density (compact or cozy) based on device size and interaction mode.

Anatomy

A date picker consists of the following elements:

  1. Date picker input field: The container in which a user enters data.
  2. Date picker button: The button that opens the date picker popover.
  3. Date picker popover: The popover that contains the calendar.

Note: For more detailed explanation of what the calendar container contains, refer to the calendar.

Date picker anatomy

Types

The date picker supports several configuration modes that control the level of selection. Each mode defines whether the component functions as a date, month, or year picker.

Basic date picker

The basic date picker allows users to enter a date by either typing it in the input field or selecting it from the calendar.

Basic date picker

Month picker

This type supports selecting a specific month. The calendar opens in month view, where only months can be selected. Users can also type a month directly in the input field.

Note: Day selection is not supported in this mode.

Date picker in month picker view

Year picker

This type allows users to pick a specific year. The calendar opens in year view, where only years can be selected. Users can also type in the input field to enter the desired year.

Note: Day and month selections are not available in this mode. Year ranges are part of the year view and cannot be selected independently.

Date picker in year picker view

Mixed calendar

The mixed calendar displays a combination of two different calendars into one calendar view. One of the calendars is defined as primary and the other one as secondary.

Note: Do not display week numbers for this type of calendar.

Date picker with mixed calendar

States

The date picker component supports different states to reflect its current interaction and validation status. Each state indicates whether the component is available for interaction and whether the entered value is valid or requires attention.

Component states

A. Enabled: Supports manual date entry in the input field and calendar-based selection via the date picker button.

B. Disabled: The component is visible but not interactive.

C. Read-only: Displays a value that cannot be edited. Supports focus for copying only.

Date picker component states

For more information, see Component States.

Interaction states

The date picker supports the following interaction states, which indicate the current interaction status of the input field and the date picker button:

A. Regular: Displays the default interaction state of the input field and the date picker button.

B. Hover on input: Displays the hover state when the cursor is over the input field.

C. Hover on button: Displays the hover state when the cursor is over the date picker button.

D. Active: Displays the focused state of the input field ready for user input.

E. Active button state: Displays the pressed state of the date picker button while the calendar is open.

Date picker interaction states

For more information, see Interaction States.

Value states

The date picker input supports four value states to indicate different validation or informational statuses:

A. Negative: Indicates an invalid date value.

B. Critical: Indicates a date value that requires attention.

C. Positive: Confirms a valid date value.

D. Information: Signals neutral status or context without implying errors or warnings.

Date picker value states

For more information, see How to Use Semantic Colors.

Value states with value state message

When users enter a date in the input field, the date picker displays value state messages that indicate whether the entered date is valid or requires attention.

These states provide visual feedback and messages that help users understand whether the value is negative (A), requires attention (B), valid (C), or contains additional information (D).

Note: The positive state does not display an input message popover.

Date picker value states with value state message

Value state messages in the date picker popover

When the date picker popover is open, the value state message appears inside the popover.

Date picker value state messages in the popover

For more information, see Value States.

Focus state

The focus state indicates which element is currently focused.

A. Unfocused: Applies to elements that are not focused.

B. Focused: Displays a visible focus highlight around the input field or the selected calendar element (date, month, year, and the previous/next buttons).

Date picker focus state

For more information, see Focus States.

Selection state

The selection state indicates whether an element is selected.

A. Unselected: Displays the default, unselected state.

B. Selected: Displays the selected state with visual distinction.

Date picker selection state

For more information, see Selection States.

Behavior and Interaction

Users can set the date in two ways:

Input field entry

When the user types a valid date in the input field, the calendar updates to reflect the entered date.

A. Regular: Displays the input field with placeholder text.

B. Input active: Displays the focused input field.

C. Date entered: Displays the entered date.

To confirm the entry, the user presses Enter or clicks outside the input field. If the value is valid, the date is applied; otherwise, a value state message appears.

Date picker input entry

Date selection

Clicking the date picker button (A) opens the calendar (B), allowing users to select a date. Once a date is selected, the value is updated in the input field, and the calendar closes automatically (C).

The calendar previous/next buttons navigate between month and year views. Selecting the current month switches the calendar to the month view, where users can choose a different month. After a month is selected, the calendar returns to the day view.

The same interaction pattern applies when selecting a year: choosing a year switches back to the day view.

Note: The user can decide not to select a date after opening the calendar. Clicking outside of the component closes the calendar and no selection is made.

Date picker date selection

Opening the date picker by another component :badge, info, large, _, SAPUI5 Only:

The date picker can be opened by a separate component, such as a button, an icon button, or a link, which acts as the trigger for the calendar popup. The opening component should include clear visible text or a tooltip describing the action (for example, “Open Date Picker”).

Date picker opened by another component

Tooltip

The date picker supports tooltips at two levels:

  • Input field (optional)
  • Date picker button.

Note: For detailed guidance on interaction patterns and tooltip behavior, please refer to the tooltip.

The calendar also supports tooltips for the following elements:

  • Today
  • Non-working days
  • Previous/next
  • Month and year.

Date picker tooltips

Responsiveness

Date picker sizes

The date picker adapts to different screen sizes and interaction modes to remain usable and efficient across all devices. Its responsive behavior ensures consistent date selection regardless of form factor.

For more information, see Content Density (Cozy and Compact).

Size S (Smartphones)

On mobile phones, the calendar opens in cozy mode and a full-screen dialog to optimize the experience for small screens. The dialog title uses the input field’s label. If no label is provided, it defaults to “Select”. Selecting a date updates the input field and closes the dialog. A Cancel button in the footer allows users to close the dialog without making a selection.

Date picker on smartphone in cozy mode

Size M and L

On size M (tablets) and L (desktops), the date picker opens as a popover containing a calendar. Selecting a date updates the value in the input field and closes the popover. Clicking anywhere outside the popover cancels the interaction and dismisses it without changing the value. Only one date can be selected. For multiple date selection, refer to the calendar.

Date picker in compact and cozy mode

Accessibility

SAP follows international standards, such as WCAG and WAI-ARIA, and strives to make our business solutions accessible and inclusive.

For more information, see Accessibility in SAP Fiori and the Accessibility Design Tools Handbook.

Keyboard navigation

The following keyboard combinations are supported by the SAPUI5 date picker component.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Tab</strong></div> <div>Moves the focus to the Input field and the date picker popover remains closed. If the focus is already on the input field, the focus is moved to the next UI element.<br>If the date picker popover is open and focus is there, the Tab key navigates between the elements inside the popover.</div> </div> <div> <div><strong>Shift + Tab</strong></div> <div>Backward navigation.</div> </div> <div> <div> <p><strong>Alt + Up Arrow or</strong></p> <p><strong>Alt + Down Arrow</strong></p> </div> <div>If the picker popover is closed, it opens and the focus moves to the calendar.<br>If the picker popover is opened, it closes and the focus moves back to the input field.</div> </div> <div> <div><strong>F4</strong></div> <div>If the picker popover is closed, it opens and the focus moves to the calendar.<br>If the picker popover is opened, the view is changed to month selection.</div> </div> <div> <div><strong>Shift + F4</strong></div> <div>If the picker popover is opened, the view is changed to year selection.</div> </div> <div> <div><strong>Enter</strong></div> <div>If the picker popover is open, selects the focused date and closes the popover.</div> </div> <div> <div><strong>Esc</strong></div> <div>If the picker popover is open, it closes without making a selection.</div> </div> <div> <div><strong>Home</strong><br><strong>End</strong></div> <div>If the focus is on the input field, the cursor moves to the first/last position.</div> </div> <div> <div> <p><strong>Right Arrow</strong></p> <p><strong>Left Arrow</strong></p> </div> <div>If the focus is on the input field, the cursor is moved one position to the right or left.</div> </div> <div> <div><strong>Ctrl + A</strong></div> <div>Selects the whole content of the input field.</div> </div> <div> <div> <p><strong>Delete</strong></p> <p><strong>Backspace</strong></p> </div> <div>Deletes the character to the right or left of the cursor.<br>If text is selected, it gets deleted.</div> </div> <div> <div> <p><strong>Shift + Right Arrow</strong></p> <p><strong>Shift + Left Arrow</strong></p> </div> <div>Selects the text to the right or left, letter by letter, starting at the cursor position.</div> </div> <div> <div> <p><strong>Shift + Ctrl + Right Arrow</strong></p> <p><strong>Shift + Ctrl + Left Arrow</strong></p> </div> <div>Selects the text to the right or left, word by word, starting at the cursor position.</div> </div> <div> <div> <p><strong>Ctrl + Right Arrow</strong></p> <p><strong>Ctrl + Left Arrow</strong></p> </div> <div>Moves the cursor to the right or left, word by word.</div> </div> <div> <div><strong>Ctrl + C оr Ctrl + Insert</strong></div> <div>Copies the selected text to the clipboard.</div> </div> <div> <div><strong>Ctrl + X оr Shift + Delete</strong></div> <div>Cuts the selected text and copies it to the clipboard.</div> </div> <div> <div><strong>Ctrl + V оr Shift + Insert</strong></div> <div>Pastes the text from the clipboard to the cursor position.</div> </div> <div> <div> <p><strong>Page Up</strong></p> <p><strong>Page Down</strong></p> </div> <div>If the focus is on the input field, the date is incremented or decremented by one day.<br>If the picker popover is opened, the focus is moved to the next or previous month. The focus stays on the same day, if possible. If the month has fewer days, the focus moves to the next possible day before (for example, January 31 will lead to February 28).</div> </div> <div> <div> <p><strong>Shift + Page Up</strong></p> <p><strong>Shift + Page Down</strong></p> </div> <div>If the focus is on the input field, the date is incremented or decremented by one month.<br>If the picker popover is opened, the focus is moved to the next or previous year.</div> </div> <div> <div> <p><strong>Shift + Ctrl + Page Up</strong></p> <p><strong>Shift + Ctrl + Page Down</strong></p> </div> <div>If the focus is on the input field, it increments or decrements the date by one year.<br>If the picker popover is opened, the date is incremented or decremented by 10 years.</div> </div>

Screen reader support

For details on screen reader support and Accessible Rich Internet Applications (ARIA), see the UI5 Screen Reader Support and WAI-ARIA Authoring.

Content

Placeholder

A custom placeholder text can be provided in the input field to indicate the expected date format. If no placeholder is provided, the date picker displays a sample date on December 31 of the current year, formatted according to the configured format pattern.

Date picker with default and custom placeholder

Display format

It is possible to customize the formatting of dates in the input. Supported formats include short, medium, and long, as well as specific custom formats. These formats adjust to different local settings that have been configured in the browser.

Date picker with different display formats

Value format

The value format defines how the date is parsed and stored internally, and depending on the level of detail specified, also determines which calendar view (days, months, or years) is presented to the user.

A. When set to YYYY-MM-DD, the picker displays days for selecting a date.
B. When set to YYYY-MM, the picker displays months for selecting a month.
C. When set to YYYY, the picker displays years for selecting a year.

Date picker value format examples

guideline
Whenever possible, we recommend using the user's default date format for clarity and familiarity.

Special dates with legend :badge, info, large, _, SAPUI5 Only:

Special dates can be marked in the calendar to visually distinguish and communicate their meaning (for example, holidays, booked/unavailable days, events, or reminders). The dates are mapped to a legend that explains their meaning. The legend comes with 20 predefined color placeholders plus the standard colors for today, selected, working, and non-working day. It can appear as a static element that stays visible next to the calendar, or as a dynamic option opened through a Special Days button. Choose the static or dynamic presentation based on available screen space and legend complexity.

Date picker with special dates and legend

Localization

The date picker supports left-to-right (LTR) and right-to-left (RTL) reading directions.

Left-to-right date picker

Right-to-left date picker

Features

Restricted date range

Define a minimum and maximum date to restrict the selectable date range. Only dates within this range can be selected.

Date picker with a minimum and a maximum date

Custom initial focus date :badge, info, large, _, SAPUI5 Only:

By default, the calendar opens with focus on the current day, but the initial focus date can be customized to any target date. For example, when a user is choosing an event end date, the focus can propose a date after the event’s start date, so the user lands in the relevant range.

Date picker with custom initial focus date

Current date :badge, info, large, _, SAPUI5 Only:

The current date can be enabled as a quick navigation through the “Today” button, which jumps the calendar to the current date. When used in month, year or year-range picker view, the calendar navigates to the default date picker view and highlights today.

Date picker with “Today” button

Footer :badge, info, large, _, SAPUI5 Only:

An optional footer with OK and Cancel buttons can be added to the date picker popover. When used, the popover remains open until the selection is either confirmed or canceled via these buttons.

Add a footer only when users need to review, confirm, or adjust multiple values before applying the selection (for example, selecting a date and then changing the month or year).

Date picker with footer

Date input shortcuts

A specific date can be entered directly into the input field by typing a shortcut and pressing Enter to confirm the selection:

Note: “Days” can be replaced with “months” or “years” in the relevant shortcuts.

Using shortcuts in the date picker input

Supported calendars

The date picker supports five calendar types – Gregorian (default), Islamic, Japanese (A), Persian (B), and Buddhist (C).

Examples of date picker with different calendar types

Calculating calendar weeks

The calendar allows defining the first day of the week, and the first week of the year. This allows you to select different calendar conventions, such as Default (A), which is based on the active format locale, ISO 8601, Middle Eastern (B), or Western Traditional (C).

Note: For more information, see the calendar.

Examples of date picker with different calendar options

Show/Hide week numbers :badge, info, large, _, Web Components Only:

The date picker allows to hiding the week numbers from the dedicated column to the left of the calendar grid. This is typically used in views where planning by week is not relevant. Whether week numbers are shown depends on the app use case and should be configured accordingly.

Date picker with and without week numbers

Framework Comparison

Some behaviors differ between frameworks due to implementation specifics. The table below summarizes the differences between SAPUI5 and SAP Web Components and lists the framework-specific patterns.

<div> <div>Feature</div> <div>SAPUI5</div> <div>SAP Web Components</div> </div> <div> <div>The date picker can be opened by another component. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23opening-the-date-picker-by-another-component-badge-info-large-_-sapui5-only">Open time picker popover by another component</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>Special dates can be marked in the calendar. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23special-dates-with-legend-badge-info-large-_-sapui5-only">Special dates with legend</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The initial focus date can be customized to any target date. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23custom-initial-focus-date-badge-info-large-_-sapui5-only">Custom initial focus date</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The “Today” button can be enabled as a quick navigation component. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23current-date-badge-info-large-_-sapui5-only">Current date</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>A footer with <em>OK</em> and <em>Cancel</em> buttons can be added to the date picker popover. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23footer-badge-info-large-_-sapui5-only">Footer</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The week numbers to the left of the calendar grid can be hidden. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdate-picker%2F%23showhide-week-numbers-badge-info-large-_-web-components-only">Show/Hide week numbers</a> section.</div> <div>Not available</div> <div>Available</div> </div>

[internal_only] To request one of these features for SAP Web Components, submit an InnerSource request.[/internal_only]

Guidelines

Components
Date/Time Picker
Calendar
Date Range Selection

Implementation

SAPUI5

Date Picker
(samples)
Date Picker
(API reference)

SAP Web Components
Date Picker

Specifications

Date Picker
(visual design)

SAP Web UI Kit

Date (Range) Picker

Guidelines

Components
Date/Time Picker
Calendar
Date Range Selection

Implementation

SAPUI5

Date Picker
(sample)
Date Picker
(API reference)

SAP Web Components
Date Picker

UI Kit (Figma)

SAP Fiori for Web UI Kit /

Date Picker