Material 3 Date Pickers

Overview

Date Pickers enable users to select a single date or a range of dates.

Material 3 Date Pickers, using MaterialDatePicker, support three variants: Docked (embedded in UI), Modal (dialog-based calendar), and Modal Date Input (text input). They offer calendar or text input modes, with constraints for date ranges and validators. This guide covers implementation, accessibility, and theming.

Getting Started

• Add Material Components for Android library dependency
• Use MaterialDatePicker for single or range selection
• Apply Theme.Material3.* for styling
• Configure constraints with CalendarConstraints

Accessibility

• Set descriptive titles via setTitleText for TalkBack
• Ensure UI elements (e.g., buttons, dates) are focusable
• Use clear labels for text input fields

Behavior and Configuration

• Configure with setSelection, setCalendarConstraints, setInputMode
• Handle input with addOnPositiveButtonClickListener
• Set constraints (e.g., start/end dates, validators)

      
val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))
calendar.set(Calendar.MONTH, Calendar.JANUARY)
val janThisYear = calendar.timeInMillis
calendar.set(Calendar.MONTH, Calendar.DECEMBER)
val decThisYear = calendar.timeInMillis
val constraintsBuilder = CalendarConstraints.Builder()
    .setStart(janThisYear)
    .setEnd(decThisYear)
    .setValidator(DateValidatorPointForward.now())
val picker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("Select date")
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
    .setCalendarConstraints(constraintsBuilder.build())
    .build()
picker.addOnPositiveButtonClickListener { selection ->
    // Handle selected date
}
picker.show(supportFragmentManager, "DATE_PICKER")
      
    

Date Picker Variants

• Docked: Embedded in UI, ideal for forms
• Modal: Dialog-based calendar for single/range selection
• Modal Date Input: Text input for date entry

Docked Date Picker

• Embedded in layouts, often with a text field
• Supports single date or range selection

Example

      
val picker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("Select appointment date")
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
    .build()
picker.addOnPositiveButtonClickListener { selection ->
    // Update text field with selected date
}
picker.show(supportFragmentManager, "DOCKED_DATE_PICKER")
      
    

Docked Date Picker Anatomy

Component	Description	Behavior
Container	Holds calendar, colorSurfaceContainerHigh	Displays calendar or menu
Text Field	Outlined, shows selected date	Triggers picker on click
Menu Buttons	Month/year selection	Toggles month/year menu
Selected Date	Highlighted date, colorPrimary	User-selected, updates field

Modal Date Picker

• Dialog-based calendar for single/range selection
• Supports navigation and confirmation buttons

Example

      
val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))
calendar.set(Calendar.MONTH, Calendar.JANUARY)
val janThisYear = calendar.timeInMillis
calendar.set(Calendar.MONTH, Calendar.DECEMBER)
val decThisYear = calendar.timeInMillis
val constraintsBuilder = CalendarConstraints.Builder()
    .setStart(janThisYear)
    .setEnd(decThisYear)
    .setValidator(DateValidatorPointForward.now())
val picker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("Select appointment date")
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
    .setCalendarConstraints(constraintsBuilder.build())
    .build()
picker.addOnPositiveButtonClickListener { selection ->
    // Handle selected date
}
picker.show(supportFragmentManager, "MODAL_DATE_PICKER")
      
    

Modal Date Picker Anatomy

Component	Description	Behavior
Container	Dialog, colorSurfaceContainerHigh	Shows calendar or year menu
Headline	Title, colorOnSurfaceVariant	Describes selection task
Selected Date/Range	Highlighted, colorPrimary	User-selected, updates on click
Controls	Navigation, confirmation buttons	Paginates or confirms selection

Modal Date Input

• Text input for manual date entry
• Supports single or range input

Example

      
val picker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("Enter date")
    .setInputMode(MaterialDatePicker.INPUT_MODE_TEXT)
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
    .build()
picker.addOnPositiveButtonClickListener { selection ->
    // Handle entered date
}
picker.show(supportFragmentManager, "MODAL_DATE_INPUT")
      
    

Modal Date Input Anatomy

Component	Description	Behavior
Container	Dialog, colorSurfaceContainerHigh	Shows text input fields
Headline	Title, colorOnSurfaceVariant	Describes input task
Text Field	Outlined, for date entry	Accepts manual date input
Controls	Confirmation buttons	Confirms entered date

Attributes and Usage

Element	Attribute	Related Method(s)	Default Value	Usage Description
Container	app:backgroundTint	N/A	?attr/colorSurfaceContainerHigh	Sets dialog background color
Container	app:shapeAppearance	N/A	?attr/shapeAppearanceCornerExtraLarge	Sets dialog corner shape
Title	N/A	Builder.setTitleText, getHeaderText	Select Date	Sets selection task title
Selected Date	app:itemFillColor	N/A	?attr/colorPrimary	Sets selected date highlight
Range	app:rangeFillColor	N/A	?attr/colorSurfaceVariant	Sets range highlight color

Theming Date Pickers

• Customize color, typography, and shape
• Use res/values/styles.xml or programmatic theming

Example

      
<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="shapeCornerFamily">cut</item>
</style>
      
    

      
<style name="Theme.App" parent="Theme.Material3.*">
    <item name="materialCalendarTheme">@style/ThemeOverlay.App.DatePicker</item>
</style>
<style name="ThemeOverlay.App.DatePicker" parent="ThemeOverlay.Material3.MaterialCalendar">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="shapeCornerFamily">cut</item>
</style>
      
    

      
val picker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("Select date")
    .setTheme(R.style.ThemeOverlay_App_DatePicker)
    .build()
picker.show(supportFragmentManager, "DATE_PICKER")
      
    

Material Design Documentation

• Adheres to Material Design guidelines for Date Pickers
• Covers design, behavior, theming specifications
• Includes accessibility and calendar constraints
• Refer to Material Design documentation for full details

FAQ

What are Material 3 Date Pickers?

• Dialogs for selecting single dates or ranges

---

How many variants are there?

• Three variants: Docked, Modal, Modal Date Input

---

When to use a Range Date Picker?

• Use for selecting date ranges, like bookings

---

How to make them accessible?

• Set descriptive titles; ensure focusable elements

---

Can I customize appearance?

• Yes, theme via res/values/styles.xml or code

---

How to add the Material 3 library?

• Include Material Components for Android library

---

Are there updates for the latest standards?

• Reflects latest Material 3 standards for Date Pickers