# Date picker

> Lets people choose a date or a range of dates, by calendar or by typing.

- Category: Selection and input
- API status: Stable
- Compose APIs: `DatePicker`, `DatePickerDialog`, `DateRangePicker`, `rememberDatePickerState`
- Interactive page: https://m3e.ljzapps.app/#components/date-picker

## When to use

Use the modal date picker in a DatePickerDialog for a single date, and the date range picker for travel or booking style choices. People can switch between the calendar and text input.

Limit selectable dates with SelectableDates, for example to exclude past days.

## 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 = rememberDatePickerState()

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

if (open) {
    DatePickerDialog(
        onDismissRequest = { open = false },
        confirmButton = { TextButton(onClick = { open = false }) { Text("OK") } },
        dismissButton = { TextButton(onClick = { open = false }) { Text("Cancel") } },
    ) {
        DatePicker(state = state)
    }
}
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `state` | `DatePickerState` |  | rememberDatePickerState(). Holds selectedDateMillis and the display mode. |
| `initialDisplayMode` | `DisplayMode` | `Picker` | Start in calendar or input mode. |
| `selectableDates` | `SelectableDates` | `AllDates` | Restricts selectable days and years. |
| `yearRange` | `IntRange` | `DatePickerDefaults.YearRange` | Selectable years. |

## Guidelines

Do:
- Preselect a sensible date.
- Explain why dates are disabled.

Don't:
- Do not use for a date far in the past, such as a birth date. Use text input.
- Do not hide the confirm button.

## Accessibility

- Days are announced with their full date. Arrow keys move between days.
- Offer text input for users who prefer the keyboard.

## Related components

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