Date pickers

Date pickers let users select a date, or a range of dates.

Android check Web Not available Flutter iOS Not available

Usage

Date pickers let users select a date or range of dates. They should be suitable for the context in which they appear.

Date pickers can be embedded into:

  • Dialogs on mobile
  • Text field dropdowns on desktop

Principles

Relevant

Date pickers can display past, present, or future dates – as relevant to the task.

Clear

Clearly indicate important dates, such as current and selected days.

Intuitive

To ensure picking a day or time is intuitive, use common picker patterns, such as a calendar.


Anatomy

Mobile calendar date picker

1. Title
2. Selected date
3. Switch-to-keyboard input icon
4. Year selection menu
5. Month pagination
6. Current date
7. Selected date

Mobile date range picker

1. Title
2. Selected date range
3. Switch to keyboard input icon
4. Month and year label
5. Current date
6. Start date
7. Selected range
8. End date

Mobile input picker

1. Title
2. Selected date
3. Switch-to-calendar view icon
4. Text field

Desktop date picker

1. Text field
2. Year and month selection
3. Month pagination
4. Today’s date
5. Selected day
6. Hover state

Mobile pickers

Mobile calendar pickers

Mobile calendar pickers can be used to select dates in the near future or past, when it’s useful to see them in a calendar month...

Usage

Mobile calendar pickers can be used to select dates in the near future or past, when it’s useful to see them in a calendar month format. They are displayed in a dialog.

Common use cases include:

  • Making a restaurant reservation
  • Scheduling a meeting

They aren’t ideal for selecting dates in the distant past or future that require more navigation, such as entering a birth date or expiration date.

Mobile calendar pickers allow selection of a single date and year.

Mobile calendar picker
DoMaintain 16dp left and right padding from the edge of the screen. The top and bottom of the picker should be vertically centered in the screen.
Don'tDon’t use more than 16dp from the left and right screen edges, as it creates smaller touch targets.
Don'tDon’t use a calendar picker to prompt for dates in the distant past or future, such as a date of birth. In these cases, use a mobile input picker or a text field instead.

Behavior

Mobile calendar pickers navigate across dates in several ways:

  • To navigate across months, swipe horizontally
  • To navigate across years, scroll vertically
  • To access the year picker, tap the year
Horizontal swiping lets the user navigate across months.
Tapping the year menu accesses the year picker. Scrolling vertically navigates across years.
Mobile calendar pickers adapt to a device’s orientation.

Mobile date range pickers

Mobile date range pickers allow selection of a range of dates. They cover the entire screen. Common use cases include: Mobile date range pickers navigate...

Usage

Mobile date range pickers allow selection of a range of dates. They cover the entire screen.

Common use cases include:

  • Booking a flight
  • Reserving a hotel
Mobile date range picker

Behavior

Mobile date range pickers navigate across dates in several ways:

  • To select a range of dates, tap the start and end dates on the calendar
  • To navigate across months, scroll vertically
Select a range of dates with the date range picker.
Scroll vertically to access different months.

Mobile date input pickers

Mobile date input pickers allow the manual entry of dates using the numbers on a keyboard. Users can input a date or a range of...

Usage

Mobile date input pickers allow the manual entry of dates using the numbers on a keyboard. Users can input a date or a range of dates in a dialog.

Mobile date input picker

Mobile date input pickers allow for keyboard input to select a date or range of dates.

Mobile date input picker
DoFor dates that don’t require a calendar view, make the mobile date input picker as the default prompt.
DoAlternatively, a text field with appropriate hint text can prompt for dates, such as in a form.

Behavior

The mobile date input picker can be accessed from any other mobile date picker, via the edit icon.

Switching from a mobile calendar picker to a mobile date input picker
Switching from a mobile date range picker to a mobile date input picker

Desktop pickers

Desktop date pickers

Desktop date pickers allow the selection of a specific date and year. The desktop date picker displays a date input field by default, and a...

Usage

Desktop date pickers allow the selection of a specific date and year. The desktop date picker displays a date input field by default, and a dropdown calendar appears when the user taps on the input field. The user can interact with either form of date entry.

Desktop date pickers are ideal for navigating dates in both the near future (or past) and the distant future (or past), as they provide multiple ways to select dates.

Desktop date picker

Behavior

Users can input dates either using a keyboard or by navigating the calendar UI; both options are immediately available when the desktop date picker is accessed.

Desktop date picker
Navigate through months by tapping the back and next arrows.
Navigate through years by tapping the dropdown.

Desktop date range pickers

Desktop date range pickers allow a range of days to be selected. They display both calendar and date input fields. Tooltips can help explain how...

Desktop date range pickers allow a range of days to be selected. They display both calendar and date input fields.

Desktop date range pickers select ranges of dates. The text field reflects the calendar dates selected.
Desktop date range picker
DoUse hover states to preview a user’s selection.
Don'tDon’t use the same style for hover and selected states.

Tooltips can help explain how to use date picker controls.

1. Tooltip used on month and year selector
2. Tooltip on day selector
3. Tooltip used on month pagination control
4. Tooltip used on selected date

Theming

Pickers can be customized to express your brand identity by altering their layout, typography, shape, color, and motion.

Pickers can be customized to express your brand identity by altering their layout, typography, shape, color, and motion.

1. Layout
2. Typography
3. Shape
4. Color
5. Motion

Color

Color can be used to create bold visual moments in a picker.

This date range picker users Crane’s brand colors.

Shape

The shape indicating selection can be customized to match the degree of boldness desired, or align to a specific style.

1. A custom color and shape for selected dates
2. The rectilinear custom shape
3. A rounded style for start and end dates and a different color for the dates in between the start and end dates help distinguish the selected period.

Layout

Date pickers span the full width of the screen.

A date picker with customized layout, shape, color, and typography

Motion

Stretch is used on the selection indicator.

Specs

Accessibility

On mobile, a date picker should allow users to enter dates manually by inputting text, without using the picker. This interaction allows multiple input methods...

On mobile, a date picker should allow users to enter dates manually by inputting text, without using the picker. This interaction allows multiple input methods and makes it accessible to those using assistive technology.

  • On desktop, the text field can be used for input.
  • On mobile, the input picker should be available from the calendar pickers via the edit icon.

Touch targets

Touch targets for mobile date pickers should be as large as possible, filling the available space. The minimum touch target size for a date picker is 32 x 32dp.

The edit icon indicates the ability to switch to the mobile input picker.
On the mobile date range picker, touch targets are maximized at 48 x 48dp.

Mobile calendar picker

Calendar header

The mobile calendar picker is a standard dialog.

Padding
• Left and right: 24dp
• Menu bar top and bottom: 16dp
• Between month name and button: 4dp
• Between month pagination: 24dp

Baseline heights
• First baseline: 32dp from top
• Second baseline: 72dp from first baseline
• Third baseline: 32 dp from bottom of header

Element size
• Edit icon: 24 x 24dp
• Month dropdown button: 24 x 24dp
• Month pagination: 24 x 24dp

Calendar view

• Dimensions: 328 x 512dp
• Left and right padding: 12dp
• Date bounding box: 40 x 40dp
• Selected date: 36 x 36dp
• Padding between dates: 4dp

Year selection view

The mobile calendar picker contains an exposed dropdown menu that enables year selection.
• Left and right margins: 24dp
• Year bounding box: 88 x 52 dp
• Selected year: 72 x 36dp

Mobile range picker

The mobile calendar picker is a full-screen dialog.

Padding
• Left and right padding: 12dp
• Padding between months: 4dp
• Edit icon padding: 16dp from right

Header
• Header height: 128dp
• Header text inset: 60dp from left margin

Baseline heights
• First baseline: 36dp from second baseline
• Second baseline: 24dp from bottom of header
• Third baseline (month name): 32dp from days of week

Element size
• Edit icon: 24 x 24dp
• Date bounding box: 48 x 48dp
• Selected date: 40 x 40dp

Mobile input picker

The mobile calendar picker is a standard dialog.

• Dimensions: 264 x 328dp
• Left and right padding: 24dp

Baseline heights
• First baseline: 28dp from top
• Second baseline: 72dp from first baseline

Element size
• Edit icon: 24 x 24 dp
• Text field: 16dp from bottom of header
• Text field height: 56dp

Desktop date picker

Calendar view

Padding
• Menu left padding: 24dp
• Menu right padding: 8dp
• Menu top padding: 16dp
• Menu bottom padding: 12dp
• Padding between month name and button: 4dp
• Padding between month pagination: 24dp
• Left and right padding of calendar area: 16dp
• Bottom padding: 8dp

Baseline heights
• First baseline: 32dp from top
• Second baseline: 36dp from first baseline

Element size
• Month dropdown button: 24 x 24dp
• Month pagination: 24 x 24dp
• Date bounding box: 32 x 32 dp
• Selected date: 28 x 28dp

Year selection view

Padding
• Left padding: 12dp
• Right padding: 20dp
• Bottom padding: 8dp
• Padding between menu and years: 4dp

Baseline height
• Menu height: 52dp

Element size
• Year bounding box: 56 x 32dp
• Selected year: 52 x 28dp

Desktop date range picker

The desktop date range picker consists of two single pickers displaying consecutive months.
• Left, right, and inside padding: 16dp
• Bottom padding: 8dp
• Month title baselines from top: 32dp
• Pagination arrows: 24 x 24dp

Using date pickers

Before you can use Material date pickers, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Date pickers let users select a date or range of dates. They should be suitable for the context in which they appear.

Date pickers can be embedded into dialogs on mobile.

Usage

The following image shows a date picker and a range date picker.

Picker and range picker examples.

API and source code:

A date picker can be instantiated with MaterialDatePicker.Builder.datePicker():

A date range picker can be instantiated with MaterialDatePicker.Builder.dateRangePicker():

To set a default selection:

The picker can be started in text input mode with:

To show the picker to the user:

Subscribe to button clicks or dismiss events with the following calls:

Finally, you can get the user selection with datePicker.selection.

Adding calendar constraints

To constrain the calendar to the beginning to the end of this year:

To open picker at a default month:

To set a validator:

You can also use DateValidatorPointBackward or use a custom one by creating a class that implements DateValidator (example of a DateValidatorWeekdays in the MDC catalog).

Finally, to set the constraint to the picker's builder:

Making date pickers accessible

Material date pickers are fully accessible and compatible with screen readers. The title of your date picker will be read when the user launches the dialog. Use a descriptive title that for the task:

Date pickers

Calendar date pickers can be used to select dates in the near future or past, when it’s useful to see them in a calendar month format. They are displayed in a dialog.

Common use cases include:

  • Making a restaurant reservation
  • Scheduling a meeting

Date picker example

The following example shows a date picker with a date selected.

Date picker with March, 5 selected

In code:

Date range pickers

Mobile date range pickers allow selection of a range of dates. They cover the entire screen.

Common use cases include:

  • Booking a flight
  • Reserving a hotel

Date range picker example

The following example shows a date range picker with a date selected.

Date range picker with March, 1 to March, 5 selected

In code:

Anatomy and key properties

The following diagram shows the elements of a date picker:

Pickers anatomy diagram

  1. Title
  2. Selected date
  3. Switch-to-keyboard input icon
  4. Year selection menu
  5. Month pagination
  6. Current date
  7. Selected date

Title

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarHeaderTitleN/A@style/Widget.MaterialComponents.MaterialCalendar.HeaderTitle
Text labelN/ABuilder.setTitleText
getHeaderText
Select Date
Colorandroid:textColorN/A?attr/colorOnPrimary
Typographyandroid:textAppearanceN/A?attr/textAppearanceOverline

Selected date

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarHeaderSelectionN/A@style/Widget.MaterialComponents.MaterialCalendar.HeaderSelection
Colorandroid:textColorN/A?attr/colorOnPrimary
Typographyandroid:textAppearanceN/A?attr/textAppearanceHeadline4

Switch-to-keyboard input icon

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarHeaderToggleButtonN/A@style/Widget.MaterialComponents.MaterialCalendar.HeaderToggleButton
Backgroundandroid:backgroundN/A?attr/actionBarItemBackground
Colorandroid:tintN/A?attr/colorOnPrimary

Year selection menu

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarYearNavigationButtonN/A@style/Widget.MaterialComponents.MaterialCalendar.YearNavigationButton
Text colorandroid:textColorN/A?attr/colorOnSurface at 60%
Icon colorapp:iconTintN/A?attr/colorOnSurface at 60%

Month pagination

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarMonthNavigationButtonN/A@style/Widget.MaterialComponents.MaterialCalendar.MonthNavigationButton
Text colorandroid:textColorN/A?attr/colorOnSurface at 60%
Icon colorapp:iconTintN/A?attr/colorOnSurface at 60%

Current date

ElementAttributeRelated method(s)Default value
Styleapp:dayTodayStyleN/A@style/Widget.MaterialComponents.MaterialCalendar.Day.Today
Text colorapp:itemTextColorN/A?attr/colorOnSurface at 87%
Stroke colorapp:itemStrokeColorN/A?attr/colorOnSurface at 87%
Stroke widthapp:itemStrokeWidthN/A1dp

Selected date

ElementAttributeRelated method(s)Default value
Styleapp:daySelectedStyleN/A@style/Widget.MaterialComponents.MaterialCalendar.Day.Selected
Background colorapp:itemFillColorN/A?attr/colorPrimary
Text colorapp:itemTextColorN/A?attr/colorOnPrimary
Stroke colorapp:itemStrokeColorN/A@color/mtrl_calendar_item_stroke_color
Stroke widthapp:itemStrokeWidthN/A0dp

Selected range

ElementAttributeRelated method(s)Default value
Colorapp:rangeFillColorN/A?attr/colorPrimary
: : : : at 12% :

Cancel button

ElementAttributeRelated method(s)Default value
Styleapp:materialCalendarHeaderCancelButtonN/A@style/Widget.MaterialComponents.MaterialCalendar.HeaderCancelButton
Text colorandroid:textColorN/A@color/mtrl_text_btn_text_color_selector
Icon colorapp:iconTintN/A?attr/colorOnPrimary

Styles and theme overlays

ElementStyle
Default
theme overlay
ThemeOverlay.MaterialComponents.MaterialCalendar
Default styleWidget.MaterialComponents.MaterialCalendar
Fullscreen
theme overlay
ThemeOverlay.MaterialComponents.MaterialCalendar.Fullscreen
Full screen styleWidget.MaterialComponents.MaterialCalendar.Fullscreen

Default style theme attribute (set inside the theme overlay): ?attr/materialCalendarStyle

Default theme attribute (set on the app's theme): ?attr/materialCalendarTheme

See the full list of styles, attributes, and theme overlays.

Theming date pickers

Date pickers support Material Theming and can be customized in terms of color, shape and typography.

Date picker theming example

API and source code:

The following example shows a date picker with Material Theming.

"Date Picker pink interactive display, grey background, and brown icons and
text."

Using theme attributes and styles in res/values/styles.xml (themes all date pickers and affects other components):

or using a default style theme attribute, styles and a theme overlay (themes all date pickers but does not affect other components):

or setting the theme in code (affects only this date picker):

No Android implementation guidance available
No Web implementation guidance available

Using date pickers

Date pickers let users select a date or range of dates. They should be suitable for the context in which they appear.

Date pickers can be embedded into:

  • Dialogs on mobile
  • Text field dropdowns on desktop

Making date pickers accessible

Flutter's APIs support accessibility setting for large fonts, screen readers, and sufficient contrast. For more information, go to Flutter's accessibility and internationalization pages.

Types

There are two types of date pickers: 1. date pickers 2. date range pickers

Date pickers

Mobile date pickers can be used to select dates in the near future or past, when it’s useful to see them in a calendar month format. They are displayed in a dialog.

Common use cases include:

  • Making a restaurant reservation
  • Scheduling a meeting

They aren’t ideal for selecting dates in the distant past or future that require more navigation, such as entering a birth date or expiration date.

Mobile date pickers allow selection of a single date and year.

Date pickers example

showDatePicker

The following example shows a date picker with a selected date of November 17, 2020 and a current date of November 13, 2020.

Date picker with selected date of November 17, 2020 and current date of November 13, 2020

Anatomy and key properties

The following diagram shows the elements of a date picker:

Date pickers anatomy diagram

  1. Title
  2. Selected date
  3. Switch-to-keyboard input icon
  4. Year selection menu
  5. Month pagination
  6. Current date
  7. Selected date

Title

 Attribute
TexthelpText property in showDatePicker

Selected date

 Attribute
DateinitialDate property in showDatePicker

Current date

 Attribute
DatecurrentDate property in showDatePicker

Date range pickers

Mobile date range pickers allow selection of a range of dates. They cover the entire screen.

Common use cases include:

  • Booking a flight
  • Reserving a hotel

Date range picker example

showDateRangePicker

The following example shows a date range picker.

Date range picker selecting November 17, 2020 to November 24, 2020, current date of November 13, 2020.

Anatomy and key properties

The following diagram shows the elements of a date range picker:

Date pickers anatomy diagram

  1. Title
  2. Selected date range
  3. Switch to keyboard input icon
  4. Month and year label
  5. Current date
  6. Start date
  7. Selected range
  8. End date

Title

 Attribute
TexthelpText property in showDateRangePicker

Selected date range

 Attribute
Date rangeinitialDateRange property in showDateRangePicker

Current date

 Attribute
DatecurrentDate property in showDateRangePicker

Theming date pickers

The following example shows a date picker that uses the Shrine theme:

Date picker with date set to November 17, 2020, header in pink and text in brown

No Flutter implementation guidance available
No iOS implementation guidance available

Up next