# Time picker

> Lets people choose a time on a dial or by typing it.

- Category: Selection and input
- API status: Expressive
- Compose APIs: `TimePicker`, `TimeInput`, `TimePickerDialog`, `rememberTimePickerState`
- Interactive page: https://m3e.ljzapps.app/#components/time-picker

## When to use

Use the dial picker for quick selection with touch or pointer, and TimeInput when the time is known and typing is faster. TimePickerDialog hosts either one, with a toggle to switch.

Honor the user's 12 or 24 hour preference through the is24Hour parameter.

## Playground

The interactive page has a playground with live property controls for this component and generated code.

## Examples

### In a dialog

```kotlin
var open by rememberSaveable { mutableStateOf(false) }
val state = rememberTimePickerState(initialHour = 9, initialMinute = 30)

Button(onClick = { open = true }) { Text("Pick a time") }

if (open) {
    TimePickerDialog(
        onDismissRequest = { open = false },
        title = { Text("Select time") },
        confirmButton = { TextButton(onClick = { open = false }) { Text("OK") } },
        dismissButton = { TextButton(onClick = { open = false }) { Text("Cancel") } },
    ) {
        TimePicker(state = state)
    }
}
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `state` | `TimePickerState` |  | rememberTimePickerState(initialHour, initialMinute, is24Hour). |
| `layoutType` | `TimePickerLayoutType` | `TimePickerDefaults.layoutType()` | Vertical for portrait, Horizontal for landscape. |
| `colors` | `TimePickerColors` | `TimePickerDefaults.colors()` | Dial, selector and period selector colors. |

## Guidelines

Do:
- Show the user's preferred format.
- Provide a keyboard alternative.

Don't:
- Do not use for durations. Use text input.
- Do not hide the dialog title.

## Accessibility

- The dial is also operable by keyboard. Arrow keys change values.
- Offer the text input mode for users who find a dial hard to use.

## Related components

- [Date picker](https://m3e.ljzapps.app/docs/components/date-picker.md)
- [Text field](https://m3e.ljzapps.app/docs/components/text-field.md)
- [Dialog](https://m3e.ljzapps.app/docs/components/dialog.md)