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

Intro

The date range selection is a UI component used to enter a date range by typing two dates in the input field or selecting a date range in the calendar. In specific scenarios, it also supports a single date entry.

Date range selection input field showing "Nov 17, 2025 - Nov 21, 2025" with a calendar button on the right.

Date range selection

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.DateRangeSelection">sap.m.DateRangeSelection</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%2FDateRangePicker%2F">ui5-daterange-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.DateRangeSelection">sap.m.DateRangeSelection</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%2FDateRangePicker%2F">ui5-daterange-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 (Range) Picker</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the date range selection to:

  • Let users select a date range.
dont
false

Don’t use the date range selection to:

  • Provide a combined date and time input component. Use the date/time picker instead.
  • Enable tasks where selecting a range is not the primary goal. Use the date picker instead.
  • Let users select from a mix of absolute and relative dates or ranges. Use the dynamic date range instead.
  • Offer selection of multiple non-consecutive days. Use the calendar instead.
  • Choose the appropriate date range selection type (date, month, or year) based on the required level of granularity.
  • Support direct date entry by typing the start and end dates into the input field.
  • Use value states and value state messages to communicate validation and status.
  • Use mixed calendar views only when users need to compare or work across different calendar systems.
  • Prefill the date range input field when it supports the workflow, providing default values that help users complete tasks faster.
  • Adapt the delimiter and date formats to regional and localization requirements.
  • Use minimum and maximum dates to restrict selectable ranges and prevent invalid or irrelevant selections.
  • Set a custom initial focus date to guide users directly to the most relevant period.
  • Mark special dates such as holidays, events, or unavailable days and explain their meaning using a legend.
  • Use an icon button, text button, or link to trigger the popover when the input field should remain hidden from view.
  • Provide tooltips on the date range selection button and the calendar to improve clarity and usability.

Anatomy

A date range selection consists of the following elements:

  1. Date range input field: Input field for entering a start and end date.
  2. Date range selection button: The button that opens the date range selection popover.
  3. Date range selection container: Popover containing the calendar.
  4. Selected date range: Highlights the chosen start and end dates in the calendar.

For more details about the calendar container, see the calendar.

Date range selection anatomy with input field above an open November 2025 calendar popover and numbered callouts identifying the input field, calendar button, date range selection popover, and selected date range.

Date range selection anatomy

Types

The date range selection supports several configuration modes that determine the level of granularity. Each mode defines whether the component operates on dates, months, or years.

Date range

The basic date range selection enables users to enter a date range by typing dates in the input field or selecting them in the calendar.

Date Range input field with placeholder text e.g. Dec 22, 2025 - Dec 31, 2025 and a calendar popover below it showing the month of November 2025.

Basic date range selection

Month range

This type supports selecting a range of whole months. The calendar opens in month view, where only months are selectable. Month values can also be entered directly in the input field to define the range.

Note: Day selection is not available in the month range mode.

Date range input field with placeholder text “e.g. Dec 22, 2025 - Dec 31, 2025” and a 2025 month picker below it displaying all twelve months from January through December.

Date range selection in month range mode

Year range

This type allows users to pick specific years. 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 the year range mode.

Date range input field with placeholder text “e.g. 2025 - 2025” and a year picker displaying years 2013 through 2032 with 2025 highlighted.

Date range selection in year range mode

Mixed calendar

Displays two calendar systems together, allowing users to view and select dates across both systems on one calendar. Each day cell shows the corresponding dates from both calendars.

Date range input field and a calendar popover showing two date systems in each day cell with corresponding dates displayed together.

Date range selection with mixed calendar

States

The date range selection component supports various states for interaction and validation. Each state indicates the component’s current status.

Component states

A. Enabled: Displays the active, editable state.

B. Disabled: Displays a visible, non-interactive state.

C. Read-only: Displays a fixed, non-editable state. Content can be selected and copied.

Three date range fields showing enabled, disabled, and read-only appearances with the value "Nov 17, 2025 - Nov 21, 2025".

Date range selection component states

For more information, see Component States.

Interaction states

The date range selection has five interaction states:

A. Regular: Displays the default interaction state of the input field and the date range selection 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 range selection button.

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

E. Active button state: The date range selection button is active, displaying the calendar.

Five date range input fields labeled A–E showing regular field, hover on field, hover on calendar button, active field, and open calendar popover.

Date range selection interaction states

For more information, see Interaction States.

Value states

The date range selection 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: Indicates neutral status or contextual information, such as a recommendation.

Four date range input fields showing date ranges with negative, critical, positive, and information status appearances.

Date range selection value states

For more information, see How to Use Semantic Colors.

Value states with value state messages

When users make a selection, the component displays a value state message in the input field indicating whether the entered date is invalid, requires attention, or contains additional information. This message also appears in the popover when it is open.

Note: The positive state does not display a value state message.

Three date range input fields and three open calendar popovers showing error, warning, and information value state messages. Messages appear below the input fields and above the calendar popovers.

Date range selection with value state messages

For more information, see Value States.

Focus state

The focus state indicates which element is currently focused.

A. Unfocused: Displays the default, non-focused state.

B. Focused: Displays a visible focus border around the input field and active calendar elements.

Two date range input fields and and a third one with a calendar popover below it showing a regular unfocused date and focused date with a border.

Date range selection focus state

For more information, see Focus States.

Selection state

The selection state indicates which date or date range is currently selected.

A. Unselected: Displays dates in their default state.

B. Selected: Highlights the selected date or date range.

Note: The dates between the start and end of the range display a distinct visual indication.

Date range input field and a calendar popover showing November 2025 with a highlighted selected range from November 17 through November 21 and November 4 as an unselected regular date.

Selection states of the date range selection component

For more information, see Selection States.

Behavior and Interaction

Selecting a date range

The users can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. This behavior works across desktops, tablets, and smartphones.

Input field entry

Typing a valid start and end date updates the selected range in the calendar.

A. Regular: Displays the default state with placeholder text.

B. Input active: Displays the focused, editable state with a visible caret.

C. Date entered: Displays the entered date range in the input field.

Three date range input fields labeled A, B, C shown as regular, active input, and date entered with a value of "Nov 17, 2025 - Nov 21, 2025".

Date range selection input entry

information
By default, the selected date range starts at 00:00:00.000 on the first date and ends at 23:59:59.999 on the second date.

Range selection

Clicking the calendar icon (A) opens the calendar to select a date range. After choosing the start date (B), hovering over subsequent dates highlights them to indicate the range (C). Selecting the end date closes the calendar and displays the selected range in the input field (D).

The same behavior applies to selecting date, month, and year ranges.

Four step sequence showing date range input field with a calendar icon (A), calendar popover with a selected start date of Nov 17, 2025 (B), calendar popover with selected date range highlighting Nov 17 - Nov 21 (C), and a completed date range Nov 17, 2025 - Nov 21, 2025 in an input field (D).

Date range selection

Single-date selection

The date range selection supports single-date input. Users can enter the same date in the input field or select the same day as both start and end date in the calendar. The same behavior applies when selecting a single month or year.

Four step sequence showing date range input field with a calendar icon (A), calendar popover with a selected date of Nov 17, 2025 (B), calendar popover with Nov 17, 2025 selected as both start and end date (C), and a completed date range Nov 17, 2025 - Nov 17, 2025 in an input field (D).

Single-date selection

No selection

The user may close the calendar without selecting a date range. Clicking outside of the component closes the calendar and no date selection is made.

Open date range selection popover from another component :badge, info, large, _, SAPUI5 Only:

The date range selection can be triggered by another component such as a text button, icon button, or link. In this case, the date range selection popover opens without an input field.

Calendar icon button, text button, and link labeled “Open Date Range Selection,” shown beside an open November 2025 calendar with Nov 17 through Nov 21 highlighted as the selected date range.

Opening date range selection popover by another component

Tooltip

The date range selection supports tooltips for the date range selection button and the calendar. For more information, see Calendar.

Date range input field with value "Nov 17, 2025 - Nov 21, 2025" and a tooltip labeled "Open Picker" above the calendar button.

Tooltip on the date range selection button

Responsiveness

Date range selection sizes

The date range selection is available in two different sizes: compact and cozy.

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

Size S (Smartphones)

On mobile devices, interaction works similarly to mouse input, but without the hover effect. Users can tap the input field to enter a date range manually or tap the calendar icon to open the calendar. For more information, see Gestures.

When the calendar opens on mobile phones, it appears in cozy mode within a full-screen dialog optimized for small screens. The dialog title uses the input field label or defaults to “Select” if no label is provided. Selecting a start and end date defines the range. Users can confirm or cancel the selection using the OK and Cancel buttons in the footer.

Two full-screen mobile dialogs titled “Select Duration” showing November 2025 calendars: the first with Nov 17 selected, and the second with Nov 17 through Nov 23 highlighted as the selected date range.

Date range selection on smartphone in cozy mode

Size M and L

On size M (tablets) and L (desktops), the date range selection opens as a popover containing a calendar. Selecting a start and end date updates the input field and closes the popover. Clicking anywhere outside the popover cancels the interaction and dismisses it without changing the values.

Two desktop calendar popovers with date range selections showing the same selected range of Nov 17 - Nov 21, 2025 in compact and cozy sizes.

Date range selection 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 range selection component.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Esc</strong></div> <div> <p>Closes the picker and restores the input field to its previous value.</p> <p>If the input field is focused and contains a value, it resets to the value it had when focus was first received.</p> </div> </div> <div> <div><strong>Tab</strong></div> <div> <p>Moves focus to the input field. Leaves the picker closed. If the field contains text, selects it.</p> <p>Moves the focus to the next interactive element in the tab chain after the component.</p> </div> </div> <div> <div><strong>Shift + Tab</strong></div> <div> <p>Backward navigation.</p> <p>Moves focus to the input field. Leaves the picker popover closed. If the field contains text, selects it.</p> <p>Moves the focus to the previous interactive element in the tab chain before the component.</p> </div> </div> <div> <div> <p><strong>Alt + Down Arrow</strong></p> <p><strong>or Alt + Up Arrow</strong></p> </div> <div> <p>Opens the picker and moves the focus to the calendar.</p> <p>Closes the picker and move the focus back to the input field.</p> </div> </div> <div> <div><strong>F4</strong></div> <div>Opens the picker and moves the focus to the calendar.</div> </div> <div> <div><strong>Page Up</strong></div> <div>Increments the date at the caret position by one day.</div> </div> <div> <div><strong>Page Down</strong></div> <div>Decrements the date at the caret position by one day.</div> </div> <div> <div><strong>Shift + Page Up</strong></div> <div>Increments the date at the caret position by one month.</div> </div> <div> <div><strong>Shift + Page Down</strong></div> <div>Decrements the date at the caret position by one month.</div> </div> <div> <div><strong>Ctrl + Shift + Page Up</strong></div> <div>Increment the date at the caret position by one year.</div> </div> <div> <div><strong>Ctrl + Shift + Page Down</strong></div> <div>Decrement the date at the caret position by one year.</div> </div> <div> <div><strong>Space or Enter</strong></div> <div>Closes the picker when the second date of the range date is selected. Input receives the selected value.</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

If no specific placeholder is defined, the date range selection displays a placeholder with a sample date range starting on December 22 of the current year and ending on December 31 of the current year, with each date formatted based on the format pattern.

Empty date range input field displaying placeholder text with value e.g. 22/12/2025 - 31/12/2025.

Date range selection with default placeholder

Delimiter

The delimiter defines the character or symbol that separates the start and end dates in the input field. By default, the component uses " - ", but this can be customized to match localization or design requirements.

Date range input field showing 05/07/2025 → 07/07/2025, using a custom arrow delimiter instead of the default date range separator.

Date range selection with customized delimiter

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.

Three date range fields showing the same range formatted as numeric dates, abbreviated month names, and full month names.

Date range selection with different format pattern

Value format

Customizing the value format defines how the start and end dates are parsed and stored internally, and determines which calendar view (days, months, or years) is displayed.

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

Three date range input fields with open calendar popovers below them, showing a day selection calendar (A), a month picker (B), and a year picker (C) for different date range formats.

Date range selection value format examples

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

The calendar supports marking special dates to indicate their meaning (for example, holidays, booked or unavailable days, events or reminders). Special dates are indicated by distinct colors explained in a legend. The legend includes 20 color placeholders plus standard colors for today, selected, working and non-working day.

July 2025 calendar showing highlighted dates and a legend for Today, Selected, Working Day, Non-Working Day, and Day 1 through Day 4, each represented by a different color swatch.

Date range selection with special dates and legend

Localization

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

Date range input field and calendar popover arranged in a left-to-right layout, with the dates reading from left to right.

Left-to-right date range selection

Date range input field and calendar popover arranged in a right-to-left layout, with the dates reading from right to left.

Right-to-left date range selection

Features

Restricted date range

Define a minimum and maximum date to restrict the selectable date range. Only dates within this range can be selected. For example, a booking application can allow users to select dates only within the next six months to ensure availability and planning accuracy.

July 2025 calendar showing a limited selectable date range from July 15 to July 23, with dates outside the range dimmed and unavailable.

Date range selection with 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. The initial focus date can be customized to any target date. For example, when selecting an event end date, the focus can be set to a date after the event’s start date to open the relevant range.

July 2025 calendar showing focus positioned on July 5, with July 4 highlighted as the current date.

Date range selection with custom initial focus date

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

The current date feature can be enabled as a quick navigation option through the “Today” icon button located in the top right in the calendar popover. This button navigates the calendar to the current date. In month, year, or year-range view, the calendar navigates to the default date range selection view and highlights today.

October 2025 calendar showing a selected date range from Oct 1 to Oct 10, with Oct 10 highlighted as today and a Today button displayed in the calendar header.

Date range selection with “Today” button

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

Add a footer with OK and Cancel buttons only when users need to review or adjust the range before confirming and the popover should remain open after selection.

By default, the popover closes after selecting a date range, month, or year.

July 2025 calendar popover with OK and Cancel buttons displayed below the calendar.

Date range selection with footer

Supported calendars

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

Three date range calendars showing the same selected date in different calendar systems: (A) Japanese calendar with year 5 Reiwa, (B) Persian calendar with year 1402 AP, and (C) Buddhist calendar with year 2566 BE.

Examples of date range selection with different calendar types

Calculating calendar weeks

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

For more information, see Calendar.

Three November 2025 calendars showing different week layouts: (A) weeks starting on Monday, (B) weeks starting on Saturday, and (C) weeks starting on Sunday, with November 3 selected in each calendar.

Examples of date range selection with different calendar options

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 range selection can be opened by another component. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/date-range-selection#open-date-range-selection-popover-from-another-component-badge-info-large-_-sapui5-only">Open date range selection popover from 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://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/date-range-selection#special-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://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/date-range-selection#custom-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://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/date-range-selection#current-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 range selection popover. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/date-range-selection#footer-badge-info-large-_-sapui5-only">Footer</a> section.</div> <div>Available</div> <div>Not available</div> </div>

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

Guidelines

Components

Calendar
Date Picker
Date/Time Picker
Dynamic Date Range
Gestures

Implementation

SAPUI5

Date Range Selection (samples)
Date Range Selection
(API reference)

SAP Web Components

Date Range Picker

Specifications

Range Selection
(visual design)

SAP Web UI Kit

Date (Range) Picker

Guidelines

Components

Calendar
Date Picker
Date/Time Picker
Dynamic Date Range
Gestures

Implementation

SAPUI5

Date Range Selection (samples)
Date Range Selection
(API reference)

SAP Web Components

Date Range Picker

UI Kit (Figma)

SAP Fiori for Web UI Kit / Date Picker