Date Pickers ​

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

Contents

• Design and API Documentation
• Using date pickers
• Calendar date picker
• Theming date pickers

Design and API Documentation ​

• Google Material3 Spec
• API reference

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 devices.

Usage ​

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

API and source code:

• MaterialDatePicker
  • Class definition
  • Class source
• CalendarConstraints
  • Class definition
  • Class source

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

val datePicker =
    MaterialDatePicker.Builder.datePicker()
        .setTitleText("Select date")
        .build()

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

val dateRangePicker =
    MaterialDatePicker.Builder.dateRangePicker()
        .setTitleText("Select dates")
        .build()

To set a default selection:

// Opens the date picker with today's date selected.
MaterialDatePicker.Builder().datePicker()
      ...
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())

// Opens the date range picker with the range of the first day of
// the month to today selected.
MaterialDatePicker.Builder.dateRangePicker()
      ...
    .setSelection(
          Pair(
            MaterialDatePicker.thisMonthInUtcMilliseconds(),
            MaterialDatePicker.todayInUtcMilliseconds()
          )
        )

The picker can be started in text input mode with:

MaterialDatePicker.Builder().datePicker()
      ...
    .setInputMode(MaterialDatePicker.INPUT_MODE_TEXT)

A DayViewDecorator can be set allowing customizing the day of month views within the picker (example of a DayViewDecorator):

MaterialDatePicker.Builder().datePicker()
      ...
    .setDayViewDecorator(new CircleIndicatorDecorator())

To show the picker to the user:

 picker.show(supportFragmentManager, "tag");

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

picker.addOnPositiveButtonClickListener {
    // Respond to positive button click.
}
picker.addOnNegativeButtonClickListener {
    // Respond to negative button click.
}
picker.addOnCancelListener {
    // Respond to cancel button click.
}
picker.addOnDismissListener {
    // Respond to dismiss events.
}

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

Adding calendar constraints ​

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

val today = MaterialDatePicker.todayInUtcMilliseconds()
val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))

calendar.timeInMillis = today
calendar[Calendar.MONTH] = Calendar.JANUARY
val janThisYear = calendar.timeInMillis

calendar.timeInMillis = today
calendar[Calendar.MONTH] = Calendar.DECEMBER
val decThisYear = calendar.timeInMillis

// Build constraints.
val constraintsBuilder =
   CalendarConstraints.Builder()
       .setStart(janThisYear)
       .setEnd(decThisYear)

To open the picker at a default month:

...
calendar[Calendar.MONTH] = Calendar.FEBRUARY
val february = calendar.timeInMillis

val constraintsBuilder =
   CalendarConstraints.Builder()
       .setOpenAt(february)

To set the first day of the week:

val constraintsBuilder =
   CalendarConstraints.Builder()
       .setFirstDayOfWeek(Calendar.MONDAY)

To set a validator:

// Makes only dates from today forward selectable.
val constraintsBuilder =
   CalendarConstraints.Builder()
       .setValidator(DateValidatorPointForward.now)

// Makes only dates from February forward selectable.
val constraintsBuilder =
   CalendarConstraints.Builder()
       .setValidator(DateValidatorPointForward.from(february))

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

Set the constraint to the picker's builder:

MaterialDatePicker.Builder().datePicker()
      ...
    .setCalendarConstraints(constraintsBuilder.build())

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 for the task:

val picker =
   MaterialDatePicker.Builder()
      ...
       .setTitleText("Select appointment date")
   ...

Calendar date picker ​

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.

In code:

val datePicker =
    MaterialDatePicker.Builder.datePicker()
        .setTitleText("Select date")
        .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
        .build()

datePicker.show()

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 range selected.

In code:

val dateRangePicker =
    MaterialDatePicker.Builder.dateRangePicker()
        .setTitleText("Select dates")
        .setSelection(
          Pair(
            MaterialDatePicker.thisMonthInUtcMilliseconds(),
            MaterialDatePicker.todayInUtcMilliseconds()
          )
        )
        .build()

dateRangePicker.show()

Anatomy and key properties ​

The following diagram shows the elements of a 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

Container ​

Title ​

Selected date ​

Switch-to-keyboard input icon ​

Year selection menu ​

Month pagination ​

Current date ​

Selected date ​

Selected range ​

Cancel button ​

Styles and theme overlays ​

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

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

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

Theming date pickers ​

Date pickers support Material Theming which can customize color, shape and typography.

Date picker theming example ​

API and source code:

• MaterialDatePicker
  • Class definition
  • Class source
• CalendarConstraints
  • Class definition
  • Class source

The following example shows a date picker with Material Theming.

Use theme attributes and styles in res/values/styles.xml, which apply to all date pickers and affect other components:

<style name="Theme.App" parent="Theme.Material3.*">
    ...
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
    <item name="shapeAppearanceMediumComponent">@style/ShapeAppearance.App.MediumComponent</item>
</style>

<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.Material3.SmallComponent">
    <item name="cornerFamily">cut</item>
</style>

<style name="ShapeAppearance.App.MediumComponent" parent="ShapeAppearance.Material3.MediumComponent">
    <item name="cornerSize">16dp</item>
</style>

Use a default style theme attribute, styles and a theme overlay which apply to all date pickers but do not affect other components:

<style name="Theme.App" parent="Theme.Material3.*">
    ...
    <item name="materialCalendarTheme">@style/ThemeOverlay.App.DatePicker</item>
</style>

<style name="ThemeOverlay.App.DatePicker" parent="@style/ThemeOverlay.Material3.MaterialCalendar">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
    <item name="shapeAppearanceMediumComponent">@style/ShapeAppearance.App.MediumComponent</item>
    <!-- Customize text field of the text input mode. -->
    <item name="textInputStyle">@style/Widget.App.TextInputLayout</item>
  </style>

Set the theme in code, which affects only this date picker:

val picker =
   MaterialDatePicker.Builder()
      ...
       .setTheme(.style.ThemeOverlay_App_DatePicker)