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

Intro

The date/time picker is a UI component that lets users select both date and time values within a unified input field. It combines a calendar view with time selection, supporting both compact and cozy display modes.

Date/time picker showing date and time of "Nov 4, 2025, 10:30 AM" in the input field with a calendar icon on the far right.

Date/time 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.DateTimePicker">sap.m.DateTimePicker</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%2FDateTimePicker%2F">ui5-date-time-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%3D195120-61096">Date Time 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.DateTimePicker">sap.m.DateTimePicker</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%2FDateTimePicker%2F">ui5-date-time-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 Time Picker</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the date/time picker to:

  • Let the user select both date and time in a single input field.
dont
false

Don’t use the date/time picker to:

  • Let the user select only a date. Use the date picker instead.
  • Let the user select only a time. Use the time picker instead.
  • Define minimum and maximum limits to restrict date and time selection to an approved range.
  • Configure minute and second step values to create predictable increments for time selection.
  • Allow users to manually enter values and rely on the component to parse valid input automatically.
  • Offer a “current date” or “current time” shortcut to help users return quickly to the present moment.
  • Use interaction and value states to provide clear visual and semantic feedback during user input.
  • Use Compact or Cozy modes to adapt the component to different screen sizes.
  • Use an icon button, text button, or link to trigger the opening of the popover when space is limited or when required by application logic.
  • Provide tooltips on the date/time picker button and calendar or clock selection interfaces to improve clarity and discoverability.
  • Support week numbers when the business use case requires weekly planning.
  • Show a timezone indicator when the input depends on regional time accuracy.
  • Use mixed calendar mode when you need to support two calendar systems in a single view.

Anatomy

A date/time picker consists of the following elements:

  1. Date/time picker input field: Displays the selected value and enables manual entry.
  2. Date/time picker button: Opens a popover for selecting date and time.
  3. Time picker container: Displays the clock interface and lets users select a time in hours, minutes and seconds.
  4. Footer: Provides the OK and Cancel actions.
  5. Date picker container: Displays the calendar for selecting a date.

Anatomy of date/time picker with numbered pointers for its different elements: input field, calendar icon button, time container, footer with OK button and cancel link, and date container.

Data/time picker anatomy

guideline
For more details on date and time containers, see the date picker and the time picker.

Types

Basic date/time picker

The date/time picker lets users select both the date (day, month, and year) and time (hours, minutes, and seconds) in a combined input.

Basic date/time picker popover with calendar and clock interface open below the input field.

Basic date/time picker

Restricted date range

The date/time picker component can be configured with minimum and maximum limits so the user can select only within the valid range.

Restricted date/time picker with minimum and maximum date limits highlighted respectively in the calendar popover.

Restricted date/time picker

States

The date/time picker incorporates various states to ensure a clear and intuitive user experience, enhancing both interaction and status validation. Each state visually communicates the component's current status and supports user navigation.

Component states

A. Enabled: The component is interactive and can receive input.

B. Disabled: The component is not interactive and cannot receive input.

C. Read-only: The value is visible but cannot be edited.

Date/time picker component states: enabled (interactive), disabled (not interactive), and read-only (visible but not editable).

Date/time picker component states

For more information, see Component States.

Interaction states

The date/time picker has five interaction states, which represent different parts of the component:

A. Regular: The default state of the input field and the button.
B. Hover on input: When the cursor hovers over the input field.
C. Hover on button: When the cursor hovers over the date/time picker button.
D. Active: The input field is focused, allowing the user to enter or edit text.
E. Active button state: The date/time picker button is active, displaying the calendar and the clock.

Date/time picker interaction states: regular, hover on input, hover on button, active input, and down.

Date/time picker interaction states

For more information, see Interaction States.

Value states

The date/time picker input field supports four value states to indicate validation and guidance: negative, critical, positive, and information. Each state is represented by a distinct semantic color to help users quickly understand the meaning: red for negative (A), yellow for critical (B), green for positive (C), and blue for information (D).

Date/time picker value states: negative (red), critical (yellow), positive (green), and information (blue).

Date/time picker value states

For more information, see How to Use Semantic Colors.

Value states with value state message

A. Negative: Signals an error and instructs the user to correct the value.

B. Critical: Indicates a potential issue that requires attention but is not an error.

C. Positive: Confirms a valid input.

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

D. Information: Displays general information or guidance that is not critical but can help users complete their tasks.

Date/time picker value state messages with popovers below the input field for negative (red), critical (yellow), positive (green), and information states (blue).

Date/time picker value states with value state message

For more information, see Value States.

Focus state

The focus state determines which component receives the user input when using an input device, such as a keyboard. By default, the focus is on the current date, but another date can be set as the initial focus if needed, depending on the app’s context or user flow.
A. Unfocused state applies to all date and time units that are not focused.
B. Focused state is visualized by an additional border around the focused date time units.

Date/time picker component displayed in unfocused and focused states on input field and popover elements with an additional border around the focused date and time units on the calendar and clock popover.

Unfocused and focused states for the date/time picker

guideline
When focus is applied to the hours, minutes, and seconds output, it maintains a selection state. However, for the AM/PM toggle button, the focus is detached and does not follow the selection.

For more information, see Focus States.

Selection state

The selection state indicates which date or time option is currently chosen by the user. The state is applied after the user selects an element, clearly distinguishing the selected element from others.
A. Unselected: The state occurs when an element is not selected, displaying the element in its regular (default) state.
B. Selected: The state shows that an element is selected and visually differs from the unselected state.

Date/time picker component displaying selected and unselected states for dates and time values, with the selected elements shown with a thin blue border.

Selected and unselected states for the date/time picker

For more information, see Selection States.

Behavior and Interaction

Manual entry

The date/time picker component provides the option to manually enter date and time values directly into the input field. The manually typed values should follow the format shown in the placeholder text.

When the user clicks the input field (A), the component becomes active and focused (B). After the user enters a valid date and time according to the expected format, the component automatically parses this value (C). The newly entered date and time then display within the field, reflecting the successful input.

Three-step sequence of manual date/time entry displaying the input field in default state, followed by active and focused and finally with valid date and time values.

Date/time picker input field interaction

Date/time picker button and popover interaction

The date/time picker component includes a dedicated button that opens a popover with calendar and clock selection controls. When the user clicks this button (A), the popover (B) appears, providing an intuitive interface for navigating through months and years, selecting a date, and adjusting time values. After choosing the desired date and time, the user confirms the selection by clicking the OK button in the footer, which closes the popover and populates the input field. If the user clicks Cancel or anywhere outside the popover, the selection is discarded, and the input field retains its placeholder text.

Two-step sequence showing a click on a date/time picker icon button, followed by opening a popover, and finally clicking OK to confirm the selection.

Date/time picker button and popover interaction

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

The date/time picker can be opened by another component such as text button, icon button, or link. In this case, the component appears as a popover with date and time selection without the input field.

Two-step sequence showing date/time picker opened as a popover by an icon button, a text button, in this example called “Open Date Time Picker”, or link without input field.

Date/time picker opened by another component

Tooltip

The date/time picker supports tooltips for the date section, the time section, and the input (optional). For more information and visuals, see the calendar and the time picker.

Tooltip “Open Picker” appearing on hover above the date/time picker icon button in the far right of the input field.

Tooltip on the date/time picker button

Responsiveness

Date/time picker sizes

The date/time picker is responsive and works on all devices and form factors. The examples below illustrate how the component adapts its size and layout based on screen resolution and interaction type. For sizes S and M use Cozy mode, whereas for size L and XL, use Compact mode. For more information, see Content Density (Cozy and Compact).

Size S (Smartphones)

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 clock. 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 canceled, and the input field remains unchanged.

Date/time picker in size S (smartphone) cozy mode with segmented Date/Time tabs.

Date/time picker in size S cozy mode

Size M (Tablets)

The popover opens as a standard overlay near the input field, offering a balanced layout that supports both touch input and manual text entry. The interaction is the same as that on Size S.

Date/time picker in size M (tablet) cozy mode with segmented Date/Time tabs.

Date/time picker in size M cozy mode

Size L (Desktops)

The date/time picker appears as a popover when the user clicks the date/time button in the input field. The user can then select the desired date from the calendar and the time from the clock. 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 canceled, and the input field remains unchanged.

If there is no value in the input field, no date is selected. The user needs to explicitly pick a date from the calendar. If a date is already selected and the user changes the year or the month, the date selection is cleared, and the user needs to pick again.

Date/time picker in size L (desktop) compact mode as popover.

Date/time picker in size L compact 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/time picker component.

Note that, in addition to the standard behaviors, the date/time picker introduces specific focus management between the date picker container and the time picker container. For more information on date selection and time navigation, see the date picker and the time picker.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Tab</strong></div> <div> <p>By default, focus starts on the <strong>current date</strong> in the date picker.<br>Pressing <strong>Tab</strong> moves the focus to the <strong>Hours output field</strong> in the time picker container.</p> <p>If a different date is defined as the initial focus, pressing <strong>Tab</strong> still moves focus to the <strong>Hours output field</strong>.</p> <p>Whenever focus is moved to a new date, pressing <strong>Tab</strong> transfers focus to the <strong>Hours output field</strong> in the time picker container.</p> </div> </div> <div> <div><strong>Shift + Tab</strong></div> <div>When focus is on the <strong>Hours output field</strong>, pressing <strong>Shift + Tab</strong> moves the focus back to the <strong>previously focused date</strong> in the date picker container.</div> </div>

Screen reader support

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

Content

Placeholder

If no specific placeholder is defined, the date/time picker displays a placeholder with a sample date of December 31 of the current year and a sample time of 23:59:58, formatted according to the format pattern. If the sample date is invalid, the closest valid year-end, highest valid month-end, or highest valid date is used in descending order.

Two date/time picker input fields showing different placeholders: one with a sample date of December 31 2025 and time of 11:59 PM; and another with a date of 12/31/2025 and sample time of 23:59:58.

Date/time picker with different format pattern

Formatting dates and times

You can use three different types of date and time formats: short, medium, and long. The formatting and order of the values differ based on the local settings that have been configured in the browser.

Three date/time picker input fields showing placeholders with different length and format: short, medium and long.

Formatting dates and times examples

guideline
For guidelines and information on the SAPUI5 date and time formatters, see formatting dates and formatting times.

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

For irregular or non-recurring events, the date/time picker supports special dates that can be highlighted in the calendar. Provide a legend whenever special dates are displayed to explain the meaning of the highlighted dates. Select from the predefined set of legend colors.

The legend 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 and time picker with special dates highlighted to indicate different event types, explained by a color-coded legend.

Date/time picker with legend

Localization

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

Date/time picker in a right-to-left (RTL) reading direction, showing localized calendar text, reversed navigation arrows, and right-aligned controls.

Right-to-left text direction in the date/time picker

Features

Timezone

Global configuration

The date/time picker can rely on both local and global configuration for timezone handling. The implementation determines which timezone is applied for the given use case.

Local configuration :badge, info, large, _, SAPUI5 Only:

The date/time picker can display a timezone next to the selected date and time. This helps users understand which timezone their input refers to, which is especially useful in applications where time accuracy across regions matters.

The timezone is shown inside the input field. When users click on it, a popover appears showing the full name of the timezone.

Date/time picker showing the selected date and time with the local time zone displayed inside the input field in country, city format “Australia, Sydney”.

Date/time picker with timezone (local configuration)

guideline
If the user needs to set a time that is time zone-sensitive, offer a select control next to the date/time picker component to choose the appropriate time zone.

Minutes and seconds step :badge, info, large, _, SAPUI5 Only:

The time picker allows configuration of step values for both minutes and seconds. By default, time values increase or decrease by 1 unit (for example 1 → 2 → 3). However, you can define a custom step increment, such as 5 or 15, to skip values accordingly. For example, if the minute step is set to 5, the sequence will follow 0 → 5 → 10 → 15, and so on.

Date/time picker with minutes configured to advance in steps of 5, illustrated by selection changing from 30 to 35 in the left and right images.

Date/time picker with minute step set to 5

guideline
Step values must be defined separately for minutes and seconds. Both are optional, and the default step value of 1 will apply if no custom value is provided.

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

The date/time picker can include shortcut buttons for quickly setting the current date or current time. When clicked, these buttons automatically update the input to reflect either today’s date or the exact current time, depending on the context.

Each button appears within the calendar or time selection view, providing users an easy way to return to the present moment without needing to scroll or manually adjust the fields.

These shortcut buttons are optional and can be enabled depending on the specific requirements of the use case.

Date/time picker with shortcut buttons (calendar icon for date and clock icon for time) that set the input to today’s date or the current time.

Date/time picker with current date and time buttons

guideline
To minimize unnecessary scrolling for the user, consider also setting default values. For time selection, using full-hour or half-hour increments (00 or 30 minutes) is often the most efficient default setting, offering convenience alongside the shortcut buttons. In certain contexts, it may be appropriate to use the current date and time as the default setting, aligning with the shortcut button functionality for a seamless user experience.

Show/hide week numbers

The date/time picker can optionally display week numbers in a dedicated column to the left of the calendar grid. This feature is typically used in views where planning by week is relevant. Whether week numbers are shown depends on the app’s use case and should be configured accordingly.

Date/time picker shown with week numbers displayed in a left column (left) and without week numbers (right).

Date/time picker with and without week numbers

Mixed calendar

The mixed calendar view supports a combination of two different calendars into one calendar view. The week numbers are not available for this type of calendar.

Date/time picker with a mixed calendar view combining a primary Islamic calendar and a secondary Gregorian calendar in a single interface.

Date/time picker with primary (Islamic) and secondary (Gregorian) calendar type

information
The date/time picker can be configured to specify how calendar weeks are calculated. This supports different calendar conventions, such as ISO 8601, Middle Eastern, or Western Traditional, among others. For more information and visuals, see the calendar.

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 input field can be hidden. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdatetime-picker%2F%23opening-the-datetime-picker-by-another-component-badge-info-large-_-sapui5-only">Open date/time picker by another component</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The date/time picker supports special dates that can be highlighted in the calendar. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdatetime-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 date/time picker can display a timezone next to the selected date and time. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdatetime-picker%2F%23local-configuration-badge-info-large-_-sapui5-only">Local configuration</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The time/picker allows configuration of step values for both minutes and seconds. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdatetime-picker%2F%23minutes-and-seconds-step-badge-info-large-_-sapui5-only">Minutes and seconds step</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The date/time picker can include a shortcut button for setting the current date or current time. For more information, see the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fui-elements%2Fdatetime-picker%2F%23current-date-and-time-badge-info-large-_-sapui5-only">Current date and time</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

Time Picker
Date Picker
Calendar
Formatting Time
Formatting Dates

Implementation

SAPUI5

Date/Time Picker
(samples)
Date/Time Picker
(API reference)

SAP Web Components
Date/Time Picker

Specifications

Date/Time Picker(visual design)

SAP Web UI Kit

Date/Time Picker

Guidelines

Components
Time Picker
Date Picker
Calendar
Formatting Time
Formatting Dates

Implementation

SAPUI5

Date/Time Picker
(samples)
Date/Time Picker
(API reference)

SAP Web Components
Date/Time Picker

UI Kit (Figma)

SAP Fiori for Web UI Kit / Date/Time Picker