Time pickers

Time pickers help users select and set a specific time. There are two variants of time pickers.

1. Time picker dial
2. Time picker input

Note: Images use various dynamic color schemes.

Design & API documentation

• Material 3 (M3) spec
• API reference

Anatomy

1. Headline
2. Time selector separator
3. Container
4. Period selector container
5. Period selector label text
6. Clock dial selector center
7. Clock dial selector track
8. Text button
9. Icon button
10. Time selector container
11. Clock dial label text
12. Clock dial container
13. Time selector label text
14. Time selector container

1. Headline
2. Time selector separator
3. Container
4. Period selector container
5. Period selector label text
6. Clock dial selector center
7. Clock dial selector track
8. Text button
9. Icon button
10. Time selector container
11. Clock dial label text
12. Clock dial container
13. Time selector label text
14. Time selector container

More details on anatomy items in the component guidelines.

Key properties

Attributes

Styles

The style attributes are assigned to the following components:

For the full list, see styles and attributes.

Variants of time pickers

Time picker dial

Dial time pickers let people set a time by moving a handle around the dial. They are often used for setting an alarm or calendar event.

Time picker input

Input time pickers allow people to set a time using a keyboard. This option is accessible from any mobile time picker interface via the keyboard icon.

Code implementation

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

Adding time picker

API and source code:

• MaterialTimePicker
  • Class definition
  • Class source

A time picker can be instantiated with MaterialTimePicker.Builder

val picker =
    MaterialTimePicker.Builder()
        .setTimeFormat(TimeFormat.CLOCK_12H)
        .setHour(12)
        .setMinute(10)
        .setTitleText("Select Appointment time")
        .build()

minute is a [0, 59] value and hour is a [0, 23] value regardless of which time format you choose.

You can use either TimeFormat.CLOCK_12H (1 ring) or TimeFormat.CLOCK_24H (2 rings), depending on the location of the device:

val isSystem24Hour = is24HourFormat(this)
val clockFormat = if (isSystem24Hour) TimeFormat.CLOCK_24H else TimeFormat.CLOCK_12H

The time picker's input mode defaults to clock mode (INPUT_MODE_CLOCK) with TimeFormat.CLOCK_12H and text input mode (INPUT_MODE_KEYBOARD) with TimeFormat.CLOCK_24H.

The time picker can be started in clock mode with:

MaterialTimePicker.Builder().setInputMode(INPUT_MODE_CLOCK)

The time picker can be started in text input mode with:

MaterialTimePicker.Builder().setInputMode(INPUT_MODE_KEYBOARD)

To show the time picker to the user:

 picker.show(fragmentManager, "tag");

Listen to positive button click, negative button click, cancel and dismiss events with the following calls:

picker.addOnPositiveButtonClickListener {
    // call back code
}
picker.addOnNegativeButtonClickListener {
   // call back code
}
picker.addOnCancelListener {
    // call back code
}
picker.addOnDismissListener {
    // call back code
}

You can get the user selection with picker.minute and picker.hour.

Making time pickers accessible

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

val picker =
   MaterialTimePicker.Builder()
       .setTitleText("Select Appointment time")
   ...

Customizing time pickers

Theming time pickers

Time pickers support the customization of color and typography.

Time picker theming example

The following example shows a time picker with Material theming.

Use theme attributes and styles in res/values/styles.xml, which styles all time pickers and affects 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="colorOnSurface">@color/shrine_pink_100</item>
    <item name="chipStyle">@style/Widget.App.Chip</item>
</style>

<style name="Widget.App.Chip" parent="Widget.Material3.MaterialTimePicker.Display">
  <item name="android:textColor">@color/shrine_diplay_text_color</item>
</style>

In res/color/shrine_diplay_text_color.xml:

<selector xmlns:android="http://schemas.android.com/apk/res/android">

  <item android:color="?attr/colorOnSecondary" android:state_enabled="true" android:state_selected="true"/>
  <item android:color="?attr/colorOnSecondary" android:state_enabled="true" android:state_checked="true"/>
  <item android:alpha="0.87" android:color="?attr/colorOnSurface" android:state_enabled="true"/>
  <item android:alpha="0.33" android:color="?attr/colorOnSurface"/>

</selector>

<style name="Widget.App.TimePicker.Clock" parent="Widget.Material3.MaterialTimePicker.Clock">
    <item name="clockFaceBackgroundColor">@color/...</item>
    <item name="clockHandColor">@color/...</item>
    <item name="clockNumberTextColor">@color/...</item>
</style>

You can also set a theme specific to the time picker

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