Intro
Date pickers can be used to select a single date or range of dates.
Date picker (left) and range picker (right) in compact size
Usage
Do
Use date and range pickers to allow users to make date and range selections.
Don't
Don’t use a date or range picker to:
- Display a visual overview of dates. Instead, use a calendar.
- Filter information based on dates. Instead, use a calendar
- Customize the picker helper text to remind the user of the date or range being selected.
- Format the selected date as needed. The default selected date format is abbreviated day of the week, followed by the month and date number.
- Format the selected range as needed. The default selected range is start date abbreviated month and date number to end date abbreviated month and date number.
- Keep the helper text consistent with the form cell label if the picker was invoked using a form cell.
- Inform the user which dates are and are not selectable before they invoke the picker. For example, the helper text in the form cell may be used to remind users that weekends may not be selected.
- Customize the range picker disabled state behavior as needed depending on the use case.
Anatomy
Date Picker
A. Header
Includes the selected date, helper text, and input icon button.
B. Year and Month Selector
Includes the year menu and month navigator.
C. Weekday Label Container
Displays labels for the seven days of the week.
D. Date Label Container
Displays the dates of a month in a grid view.
E. Footer
Includes the “Clear”, “Cancel”, and “OK” label buttons.
Anatomy of the date picker
Range Picker
The range picker is a full-page dialog.
A. Top App Bar
Includes the “Close” icon button that cancels any changes made to the selected date range and closes the picker dialog.
B. Header
Includes the selected date range, helper text, and input icon button.
C. Weekday Label Container
Displays labels for the seven days of the week.
D. Date Label Container
Displays the dates of the visible months in a grid view.
E. Footer
Includes the “Clear”, “Cancel”, and “OK” label buttons.
The “Clear” button is available in Jetpack Compose only.
Anatomy of the range picker
Behavior and Interaction
Date Picker
Selection
To select a date, users may tap on a date label. Today’s date is selected by default.
The default selected date may be customized, for example, no date selected (empty state).
Selecting a date in the date picker
Year Navigation
To navigate between years, users may tap the year month drop-down button. This displays a list of years in place of the date labels. If the user selects a new year, the picker navigates to the current month of the newly selected year.
Navigating years in the date picker
Month Navigation
To navigate between months, users may tap the left or right chevron icon buttons or swipe the date label container area left or right.
Navigating months in the date picker
Range Picker
Selection
To select a date range, users may tap on a starting date label followed by an end date label. Today’s date to today’s date is selected by default. The default selected range may be customized, for example, no range selected (empty state).
- If a start date is already selected and the user selects a date before the selected start date, the newly selected date becomes the start date.
- If a start and end date are already selected and the user selects another date, the newly selected date becomes the start date and the end date is cleared.
By default, the user can select a range with disabled states in between. The behavior for disabled dates in the range picker may be customized. For example:
- Date ranges may be customized to not allow disabled states in between. For this case, consider updating the start date if the user taps on an end date that would cause the range to span a disabled date(s).
- End date states may be dynamic depending on the chosen start date. For this case, consider adding logic to update the state of the end dates after a start date has been chosen.
Selecting a range in the range picker
Navigation
To navigate between months, users may swipe up and down on the date label container area. The date labels scroll infinitely unless a minimum and/or maximum date has been defined.
To choose an end date that is far from the start date more efficiently, the input picker dialog may be used to type the start and end dates instead.
Navigating through months in the range picker
Clear Selection
Tapping on the “Clear” label button in the date or range dialog footer clears the selected date or range. This also applies to the input variant of both the date and range pickers. When a selection is cleared, the pickers show an empty state text in the selected date or range area.
The “Clear” functionality is available in Jetpack Compose only.
Clearing the selection in the date picker (left), range picker (center), and date input picker (right)
Cancel and OK
Tapping on the “Cancel” label button cancels any changes made to the date or range selection and closes the picker dialog. Tapping on the “OK” label button saves any changes made to the date or range selection and closes the picker dialog.
Bounding Dates
An upper date or lower date bound (inclusive) may be set in the date or range picker. If an upper/lower date bound is set, the end user may not select a date after/before the set date bounds. The pickers can’t be navigated to a month after/before the upper/lower date bound.
- The lower date bound is the earliest day a user can select; all dates before the lower bound are disabled.
- The upper date bound is the last day a user can select; all dates after the lower bound are disabled.
If an upper/lower date bound is set, it is highly advised that the selectable dates are made clear before the user opens the picker dialogs. This helps avoid confusion about why certain dates are disabled and non-navigable.
Date picker interaction with lower bounding date selection (today, August 8, 2025)
Variations
Input Mode
The date and range pickers include an input mode. This mode may be customized to be shown as the default dialog when the picker is triggered. The user may switch to the picker selection mode by tapping on the calendar icon button in the dialog header.
Date input dialog (left) and range input dialog (right)
Picker Empty State
The date and range pickers include an empty state. This state is displayed when the user clears a selection. The pickers may be customized to show the empty state by default.
Empty states from left to right: date picker, range picker, date input picker, range input picker
Date Picker Label States
-
Default – days of the month being displayed
-
Today – the current system date
-
Today + Selected – the current system date that is also selected
-
This state is available in Jetpack Compose only
-
Selected – the selected date
-
Disabled – dates that cannot be selected. Disabled dates can be customized. For example:
- Singular dates can be disabled, for example, a holiday. b. Specific date types can be disabled, for example, weekends.
- Dates outside of lower and/or upper date bounds, for example, dates after today only.
Date picker states from left to right: default, today, selected, today + selected, disabled
Range Picker Label States
-
Default – days of the month being displayed
-
Today – the current system date
-
Selected – the selected starting date when no end date is selected
-
Today + Selected – the current system date that is also selected as the start date
-
This state is available in Jetpack Compose only
-
Range start – the selected starting date when an end date is selected
-
Range middle – dates between the selected starting and end dates
-
Range end – the selected end date
-
Disabled – dates that cannot be selected. Disabled dates can be customized. For example:
- Singular dates can be disabled, for example, a holiday.
- Specific date types can be disabled, for example, weekends.
- Dates outside of lower and/or upper date bounds, for example, dates after today only.
Range picker states from left to right: default, today, selected, today + selected, range start, range middle, range end, disabled
Input Picker Error States
If specific disabled dates are set, it is highly advised that the selectable dates are made clear before the user opens the picker dialogs. This is to avoid confusion about why certain dates are disabled and non-navigable.
Disabled State
This error triggers when the user inputs a disabled date into the input picker and the date is not out of date bounds.
Disabled state error message in a date input picker
Out of Bounds
This error triggers when the user inputs a date outside of the set bounds.
Out of bounds error message in a date input picker (top) and range input picker (bottom)
End Date before Start Date
This error triggers when the user inputs an end date that occurs before the start date.
End date before start date error message in a range input picker
Invalid Date
This error triggers when the user inputs an impossible date.
Invalid date error message in a date input picker
Status Indicators
The picker date labels can display status information via status indicators, which should be a set of simple icons that are easy to recognize. A legend row is required to ensure that the status meanings are accessible. These status indicators are available in Jetpack Compose only. The ViewBased status indicators do not include a legend and only provide for one circular indicator.
Date picker with status indicators and legend
Alternate Calendar
The picker date labels can show two calendar types on the same frame. The alternate calendar date label is displayed below the primary calendar date label. The alternate calendar is available in Jetpack Compose only. Below are the available calendar types for both the primary and the secondary calendar:
- Gregorian (default primary calendar)
- Chinese
- Hebrew
- Islamic
- Japanese
Date picker with alternate calendar labels
Adaptive Design
Range Picker
The date label grid in the range picker full-page dialog adapts to different window sizes.
In compact windows, the width of the week labels and date labels expand to full width.
In medium windows, the week labels and date labels are fixed to 72dp.
In expanded windows, the week labels and date labels are fixed to 100dp.
Range picker adapting to compact (left), medium (middle), and expanded windows (right)
Input Mode Dialog
The input mode is displayed by default for devices with small heights since the input mode dialogs are smaller than the selection mode dialogs. This can be customized if needed.
Date input picker on a small screen height with keyboard hidden
Resources
Development: DateTimePickerFormCell (ViewBased), DurationPickerFormCell (ViewBased)
SAP Fiori for iOS: Pickers
Material Design: Date Pickers, Time Pickers
Related Components/Patterns: Date & Time Picker Form Cell, Dialogs, Time Pickers