# DatePicker

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePicker.composable#DatePicker(androidx.compose.material3.DatePickerState,androidx.compose.ui.Modifier,androidx.compose.material3.DatePickerFormatter,androidx.compose.material3.DatePickerColors,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.focus.FocusRequester)( state: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerState, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, dateFormatter: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter, colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors, title: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, headline: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, showModeToggle: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, focusRequester: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester? )` [Material Design date picker](https://m3.material.io/components/date-pickers/overview) | Cmn |

## Functions

### DatePicker

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/DatePicker.kt+function:DatePicker)

```
@Composable
fun DatePicker(
    state: DatePickerState,
    modifier: Modifier = Modifier,
    dateFormatter: DatePickerFormatter = remember { DatePickerDefaults.dateFormatter() },
    colors: DatePickerColors = DatePickerDefaults.colors(),
    title: (@Composable () -> Unit)? = {
        DatePickerDefaults.DatePickerTitle(
            displayMode = state.displayMode,
            modifier = Modifier.padding(DatePickerTitlePadding),
            contentColor = colors.titleContentColor,
        )
    },
    headline: (@Composable () -> Unit)? = {
        DatePickerDefaults.DatePickerHeadline(
            selectedDateMillis = state.selectedDateMillis,
            displayMode = state.displayMode,
            dateFormatter = dateFormatter,
            modifier = Modifier.padding(DatePickerHeadlinePadding),
            contentColor = colors.headlineContentColor,
        )
    },
    showModeToggle: Boolean = true,
    focusRequester: FocusRequester? = remember { FocusRequester() }
): Unit
```

[Material Design date picker](https://m3.material.io/components/date-pickers/overview)

Date pickers let people select a date and preferably should be embedded into Dialogs. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerDialog.composable#DatePickerDialog(kotlin.Function0,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Function0,androidx.compose.ui.graphics.Shape,androidx.compose.ui.unit.Dp,androidx.compose.material3.DatePickerColors,androidx.compose.ui.window.DialogProperties,kotlin.Function1)`.

By default, a date picker lets you pick a date via a calendar UI. However, it also allows switching into a date input mode for a manual entry of dates using the numbers on a keyboard.

![Date picker
image](https://developer.android.com/images/reference/androidx/compose/material3/date-picker.png)

A simple DatePicker looks like:

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.Button
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerState
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column(
    modifier = Modifier.verticalScroll(rememberScrollState()),
    verticalArrangement = Arrangement.spacedBy(8.dp),
) {
    // Pre-select a date for January 4, 2020
    val datePickerState = rememberDatePickerState(initialSelectedDateMillis = 1578096000000)
    DatePicker(state = datePickerState, modifier = Modifier.padding(16.dp))

    Text(
        "Selected date timestamp: ${datePickerState.selectedDateMillis ?: "no selection"}",
        modifier = Modifier.align(Alignment.CenterHorizontally),
    )

    Button(
        onClick = {
            datePickerState.selectedDateMillis = System.currentTimeMillis()
            datePickerState.displayedMonthMillis = System.currentTimeMillis()
        },
        modifier = Modifier.align(Alignment.CenterHorizontally),
    ) {
        Text("Set date to today")
    }
}
```

A DatePicker with an initial UI of a date input mode looks like:

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerState
import androidx.compose.material3.DisplayMode
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
    val state = rememberDatePickerState(initialDisplayMode = DisplayMode.Input)
    DatePicker(state = state, modifier = Modifier.padding(16.dp))

    Text(
        "Entered date timestamp: ${state.selectedDateMillis ?: "no input"}",
        modifier = Modifier.align(Alignment.CenterHorizontally),
    )
}
```

A DatePicker can also be initialized with Java Time APIs when running on Android with API 26 and above:

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerState
import androidx.compose.material3.Text
import androidx.compose.material3.getSelectedDate
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column(
    modifier = Modifier.verticalScroll(rememberScrollState()),
    verticalArrangement = Arrangement.spacedBy(8.dp),
) {
    // Pre-select a date for April 15, 2023
    val datePickerState =
        rememberDatePickerState(initialSelectedDate = LocalDate.of(2023, 4, 15))
    DatePicker(state = datePickerState, modifier = Modifier.padding(16.dp))

    Text(
        "Selected date: ${datePickerState.getSelectedDate() ?: "no selection"}",
        modifier = Modifier.align(Alignment.CenterHorizontally),
    )
}
```

A DatePicker with a provided `https://developer.android.com/reference/kotlin/androidx/compose/material3/SelectableDates` that blocks certain days from being selected looks like:

```kotlin
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerState
import androidx.compose.material3.SelectableDates
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

val datePickerState =
    rememberDatePickerState(
        selectableDates =
            object : SelectableDates {
                // Blocks Sunday and Saturday from being selected.
                override fun isSelectableDate(utcTimeMillis: Long): Boolean {
                    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
                        val dayOfWeek =
                            Instant.ofEpochMilli(utcTimeMillis)
                                .atZone(ZoneId.of("UTC"))
                                .toLocalDate()
                                .dayOfWeek
                        dayOfWeek != DayOfWeek.SUNDAY && dayOfWeek != DayOfWeek.SATURDAY
                    } else {
                        val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))
                        calendar.timeInMillis = utcTimeMillis
                        calendar[Calendar.DAY_OF_WEEK] != Calendar.SUNDAY &&
                            calendar[Calendar.DAY_OF_WEEK] != Calendar.SATURDAY
                    }
                }

                // Allow selecting dates from year 2023 forward.
                override fun isSelectableYear(year: Int): Boolean {
                    return year > 2022
                }
            }
    )

Column(
    modifier = Modifier.verticalScroll(rememberScrollState()),
    verticalArrangement = Arrangement.spacedBy(8.dp),
) {
    DatePicker(state = datePickerState)
    Text(
        "Selected date timestamp: ${datePickerState.selectedDateMillis ?: "no selection"}",
        modifier = Modifier.align(Alignment.CenterHorizontally),
    )
}
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerState` | state of the date picker. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/rememberDatePickerState.composable#rememberDatePickerState(kotlin.Long,kotlin.Long,kotlin.ranges.IntRange,androidx.compose.material3.DisplayMode,androidx.compose.material3.SelectableDates)`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to this date picker |
| `dateFormatter: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter = remember { DatePickerDefaults.dateFormatter() }` | a `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter` that provides formatting skeletons for dates display |
| `colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors = DatePickerDefaults.colors()` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors` that will be used to resolve the colors used for this date picker in different states. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerDefaults#colors()`. |
| `title: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = { DatePickerDefaults.DatePickerTitle( displayMode = state.displayMode, modifier = Modifier.padding(DatePickerTitlePadding), contentColor = colors.titleContentColor, ) }` | the title to be displayed in the date picker |
| `headline: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = { DatePickerDefaults.DatePickerHeadline( selectedDateMillis = state.selectedDateMillis, displayMode = state.displayMode, dateFormatter = dateFormatter, modifier = Modifier.padding(DatePickerHeadlinePadding), contentColor = colors.headlineContentColor, ) }` | the headline to be displayed in the date picker |
| `showModeToggle: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | indicates if this DatePicker should show a mode toggle action that transforms it into a date input |
| `focusRequester: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester? = remember { FocusRequester() }` | a focus requester that will be used to focus the text field when the date picker is in an input mode. Pass `null` to not focus the text field if that's the desired behavior. |