rememberDateRangePickerState

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

Creates a DateRangePickerState for a DateRangePicker that is remembered across compositions.

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

Parameters
initialSelectedStartDateMillis timestamp in UTC milliseconds from the epoch that represents an initial selection of a start date. Provide a null to indicate no selection.
initialSelectedEndDateMillis timestamp in UTC milliseconds from the epoch that represents an initial selection of an end 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 initialSelectedStartDateMillis 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 range 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 rememberDateRangePickerState(
    initialSelectedStartDate: LocalDate?,
    initialSelectedEndDate: LocalDate?,
    initialDisplayedMonth: YearMonth? = initialSelectedStartDate?.let { YearMonth.from(it) },
    yearRange: IntRange = DatePickerDefaults.YearRange,
    initialDisplayMode: DisplayMode = DisplayMode.Picker,
    selectableDates: SelectableDates = DatePickerDefaults.AllDates,
): DateRangePickerState

Creates a DateRangePickerState for a DateRangePicker that is remembered across compositions.

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

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

  • initialSelectedStartDate is used to set DateRangePickerState.selectedStartDateMillis.
  • initialSelectedEndDate is used to set DateRangePickerState.selectedEndDateMillis.
  • initialDisplayedMonth is used to set DateRangePickerState.displayedMonthMillis, based on the first day of that month.

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

Parameters
initialSelectedStartDate a LocalDate that represents an initial selection of a start date. Provide a null to indicate no selection.
initialSelectedEndDate a LocalDate that represents an initial selection of an end date. 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 initialSelectedStartDate 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 range 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

DateRangePickerApi26Sample

@RequiresApi(Build.VERSION_CODES.O)
@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun DateRangePickerApi26Sample() {
    // Decoupled snackbar host state from scaffold state for demo purposes.
    val snackState = remember { SnackbarHostState() }
    val snackScope = rememberCoroutineScope()
    SnackbarHost(hostState = snackState, Modifier.zIndex(1f))
    // Creates a state with pre-selected date range.
    val state =
        rememberDateRangePickerState(
            initialSelectedStartDate = LocalDate.of(2023, 4, 15),
            initialSelectedEndDate = LocalDate.of(2023, 4, 20),
        )
    Column(modifier = Modifier.fillMaxSize(), verticalArrangement = Arrangement.Top) {
        // Add a row with "Save" and dismiss actions.
        Row(
            modifier =
                Modifier.fillMaxWidth()
                    .background(DatePickerDefaults.colors().containerColor)
                    .padding(start = 12.dp, end = 12.dp),
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.SpaceBetween,
        ) {
            TooltipBox(
                positionProvider =
                    TooltipDefaults.rememberTooltipPositionProvider(TooltipAnchorPosition.Above),
                tooltip = { PlainTooltip { Text("Close") } },
                state = rememberTooltipState(),
            ) {
                IconButton(onClick = { /* dismiss the UI */ }) {
                    Icon(Icons.Filled.Close, contentDescription = "Close")
                }
            }
            TextButton(
                onClick = {
                    snackScope.launch {
                        val range = state.getSelectedStartDate()!!..state.getSelectedEndDate()!!
                        snackState.showSnackbar("Saved range: $range")
                    }
                },
                enabled = state.getSelectedEndDate() != null,
            ) {
                Text(text = "Save")
            }
        }
        DateRangePicker(state = state, modifier = Modifier.weight(1f))
    }
}