rememberDatePickerState

Composable Function
Common
@Composable
fun rememberDatePickerState(
    @Suppress("AutoBoxing") initialSelectedDateMillis: Long? = null,
    @Suppress("AutoBoxing") initialDisplayedMonthMillis: Long? = initialSelectedDateMillis,
    yearRange: IntRange = DatePickerDefaults.YearRange,
    initialDisplayMode: DisplayMode = DisplayMode.Picker,
    selectableDates: SelectableDates = DatePickerDefaults.AllDates,
): DatePickerState

Creates a DatePickerState for a DatePicker that is remembered across compositions.

To create a date picker state outside composition, see the DatePickerState function.

Parameters
initialSelectedDateMillis timestamp in UTC milliseconds from the epoch that represents an initial selection of a date. Provide a null to indicate no selection.
initialDisplayedMonthMillis timestamp in UTC milliseconds from the epoch that represents an initial selection of a month to be displayed to the user. By default, in case an initialSelectedDateMillis is provided, the initial displayed month would be the month of the selected date. Otherwise, in case null is provided, the displayed month would be the current one.
yearRange an IntRange that holds the year range that the date picker will be limited to
initialDisplayMode an initial DisplayMode that this state will hold
selectableDates a SelectableDates that is consulted to check if a date is allowed. In case a date is not allowed to be selected, it will appear disabled in the UI.
JvmAndAndroid
@RequiresApi(26)
@Composable
fun rememberDatePickerState(
    initialSelectedDate: LocalDate?,
    initialDisplayedMonth: YearMonth? = initialSelectedDate?.let { YearMonth.from(it) },
    yearRange: IntRange = DatePickerDefaults.YearRange,
    initialDisplayMode: DisplayMode = DisplayMode.Picker,
    selectableDates: SelectableDates = DatePickerDefaults.AllDates,
): DatePickerState

Creates a DatePickerState for a DatePicker that is remembered across compositions.

Note: This composable uses LocalDate and YearMonth. For a lower-level composable that uses UTC milliseconds, see the other rememberDatePickerState overload.

The initial values are converted to UTC milliseconds at the start of the day (midnight):

  • initialSelectedDate is used to set DatePickerState.selectedDateMillis.
  • initialDisplayedMonth is used to set DatePickerState.displayedMonthMillis, based on the first day of that month.

To create a date picker state outside composition, see the DatePickerState function.

Parameters
initialSelectedDate a LocalDate for an initial date selection. Provide a null to indicate no selection.
initialDisplayedMonth an optional YearMonth for an initial month that will be displayed to the user. By default, in case an initialSelectedDate is provided, the initial displayed month would be the month of the selected date. You may provide a different initial month, or null to display the current one.
yearRange an IntRange that holds the year range that the date picker will be limited to
initialDisplayMode an initial DisplayMode that this state will hold
selectableDates a SelectableDates that is consulted to check if a date is allowed. In case a date is not allowed to be selected, it will appear disabled in the UI.

Code Examples

DatePickerApi26Sample

@RequiresApi(Build.VERSION_CODES.O)
@Preview
@Composable
fun DatePickerApi26Sample() {
    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),
        )
    }
}