# Time pickers
[Time pickers](https://material.io/components/time-pickers) help users select and set a specific time.
**Contents**
* [Design & API Documentation](#design-api-documentation)
* [Using time pickers](#using-time-pickers)
* [Time pickers](#time-pickers)
* [Theming time pickers](#theming-time-pickers)
## Design & API Documentation
* [Google Material3 Spec](https://material.io/components/time-pickers/overview)
* [API Reference](https://developer.android.com/reference/com/google/android/material/timepicker/package-summary)
## Using time pickers
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](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
page.
### Usage
API and source code:
* `MaterialTimePicker`
* [Class definition](https://developer.android.com/reference/com/google/android/material/timepicker/MaterialTimePicker)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/timepicker/MaterialTimePicker.java)
A time picker can be instantiated with `MaterialTimePicker.Builder`
```kt
val picker =
MaterialTimePicker.Builder()
.setTimeFormat(TimeFormat.CLOCK_12H)
.setHour(12)
.setMinute(10)
.setTitleText("Select Appointment time")
.build()
```
`minute` is a *[0, 60)* 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:
```kt
MaterialTimePicker.Builder().setInputMode(INPUT_MODE_CLOCK)
```
The time picker can be started in text input mode with:
```kt
MaterialTimePicker.Builder().setInputMode(INPUT_MODE_KEYBOARD)
```
To show the time picker to the user:
```kt
picker.show(fragmentManager, "tag");
```
Subscribe 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:
```kt
val picker =
MaterialTimePicker.Builder()
.setTitleText("Select Appointment time")
...
```
### Anatomy and key properties
A Time Picker has a title, an input method, a clock dial, an icon to switch input
and an AM/PM selector.
1. Title
2. Interactive display and time input for hour and minutes
3. Clock dial
4. Icon button to switch to time input
5. AM/PM selector
#### Attributes
Element | Attribute | Related method(s) | Default value
------------------------------- | ------------------------------ | ----------------------------------------------------- | -------------
**Hour** | `N/A` | `Builder.setHour`
`MaterialTimePicker.getHour` | `0`
**Minute** | `N/A` | `Builder.setMinute`
`MaterialTimePicker.getMinute` | `0`
**Title** | `N/A` | `Builder.setTitleText` | `Select Time`
**Keyboard Icon** | `app:keyboardIcon` | `N/A` | `@drawable/ic_keyboard_black_24dp`
**Clock Icon** | `app:clockIcon` | `N/A` | `@drawable/ic_clock_black_24dp`
**Clock face Background Color** | `app:clockFaceBackgroundColor` | `N/A` | `?attr/colorSurfaceContainerHighest`
**Clock hand color** | `app:clockNumberTextColor` | `N/A` | `?attr/colorPrimary`
**Clock Number Text Color** | `app:clockNumberTextColor` | `N/A` | `?attr/colorOnBackground`
#### Styles
Element | Style
----------------- | ----------------------------------
**Default style** | `Widget.Material3.MaterialTimePicker`
Default style theme attribute: `?attr/materialTimePickerStyle`
The style attributes are assigned to the following components:
Element | Affected component | Default
------------------------ | ---------------------------------- | ---------------------
**chipStyle** | Number inputs in the clock mode | `@style/Widget.Material3.MaterialTimePicker.Display`
**materialButtonOutlinedStyle** | AM/PM toggle | `@style/Widget.Material3.MaterialTimePicker.Button`
**imageButtonStyle** | Keyboard/Text Input button | `@style/Widget.Material3.MaterialTimePicker.ImageButton`
**materialClockStyle** | Clock Face of the Time Picker | `@style/Widget.Material3.MaterialTimePicker.Clock`
See the full list of
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/timepicker/res/values/styles.xml)
and
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/timepicker/res/values/attrs.xml).
## Theming time pickers
Time Pickers support
[Material Theming](https://material.io/components/sliders#theming) which can
customize 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:
```xml
```
```xml
```
In res/color/shrine_diplay_text_color.xml:
```xml