DateRangePickerState

Function

Common

@ExperimentalMaterial3Api
fun DateRangePickerState(
    locale: CalendarLocale,
    @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 most cases, you are advised to use the rememberDateRangePickerState when in a composition.

Note that in case you provide a locale that is different than the default platform locale, you may need to ensure that the picker's title and headline are localized correctly. The following sample shows one possible way of doing so by applying a local composition of a LocalContext and LocaleConfiguration.

Parameters


locale	the `CalendarLocale` that will be used when formatting dates, determining the input format, displaying the week-day, determining the first day of the week, and more. Note that in case the provided `CalendarLocale` differs from the platform's default Locale, you may need to ensure that the picker's title and headline are localized correctly, and in some cases, you may need to apply an RTL layout.
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 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

Android

@RequiresApi(Build.VERSION_CODES.O)
@ExperimentalMaterial3Api
fun DateRangePickerState(
    locale: CalendarLocale,
    initialSelectedStartDate: LocalDate?,
    initialSelectedEndDate: LocalDate? = null,
    initialDisplayedMonth: YearMonth? = initialSelectedStartDate?.let { YearMonth.from(it) },
    yearRange: IntRange = DatePickerDefaults.YearRange,
    initialDisplayMode: DisplayMode = DisplayMode.Picker,
    selectableDates: SelectableDates = DatePickerDefaults.AllDates,
): DateRangePickerState

Creates a DateRangePickerState.

For most cases, you are advised to use the rememberDateRangePickerState when in a composition.

Parameters


locale	the `CalendarLocale` that will be used when formatting dates, determining the input format, displaying the week-day, determining the first day of the week, and more. Note that in case the provided `CalendarLocale` differs from the platform's default Locale, you may need to ensure that the picker's title and headline are localized correctly, and in some cases, you may need to apply an RTL layout.
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` that represents an initial selection of a month to 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. 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

Code Examples

DatePickerCustomLocaleSample

@RequiresApi(Build.VERSION_CODES.N)
@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun DatePickerCustomLocaleSample() {
    val preferredLocales = LocaleList.forLanguageTags("HE")
    val config = Configuration()
    config.setLocales(preferredLocales)
    val newContext = LocalContext.current.createConfigurationContext(config)
    CompositionLocalProvider(
        LocalContext provides newContext,
        LocalConfiguration provides config,
        LocalLayoutDirection provides LayoutDirection.Rtl,
    ) {
        Column(
            modifier = Modifier.verticalScroll(rememberScrollState()),
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            // Pre-select a date for January 4, 2020
            // Initialize date picker with the preferred locale. Here we create a state directly,
            // but since the Locale was set at the CompositionLocalProvider through a Configuration,
            // a `val datePickerState = rememberDatePickerState(...)` will have the same effect.
            val datePickerState = remember {
                DatePickerState(
                    initialSelectedDateMillis = 1578096000000,
                    // Set to "HE" locale.
                    locale = preferredLocales.get(0),
                )
            }
            DatePicker(state = datePickerState, modifier = Modifier.padding(16.dp))
            Text(
                "Selected date timestamp: ${datePickerState.selectedDateMillis ?: "no selection"}",
                modifier = Modifier.align(Alignment.CenterHorizontally),
            )
        }
    }
}

DatePickerCustomLocaleApi26Sample

@RequiresApi(Build.VERSION_CODES.O)
@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun DatePickerCustomLocaleApi26Sample() {
    val preferredLocales = LocaleList.forLanguageTags("HE")
    val config = Configuration()
    config.setLocales(preferredLocales)
    val newContext = LocalContext.current.createConfigurationContext(config)
    CompositionLocalProvider(
        LocalContext provides newContext,
        LocalConfiguration provides config,
        LocalLayoutDirection provides LayoutDirection.Rtl,
    ) {
        Column(
            modifier = Modifier.verticalScroll(rememberScrollState()),
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            // Pre-select a date for January 4, 2020
            // Initialize date picker with the preferred locale. Here we create a state directly,
            // but since the Locale was set at the CompositionLocalProvider through a Configuration,
            // a `val datePickerState = rememberDatePickerState(...)` will have the same effect.
            val datePickerState = remember {
                DatePickerState(
                    initialSelectedDate = LocalDate.of(2020, 1, 4),
                    // Set to "HE" locale.
                    locale = preferredLocales.get(0),
                )
            }
            DatePicker(state = datePickerState, modifier = Modifier.padding(16.dp))
            Text(
                "Selected date: ${datePickerState.getSelectedDate() ?: "no selection"}",
                modifier = Modifier.align(Alignment.CenterHorizontally),
            )
        }
    }
}