DatePickerState

Function

Common

@ExperimentalMaterial3Api
fun DatePickerState(
    locale: CalendarLocale,
    @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 most cases, you are advised to use the rememberDatePickerState 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.
initialSelectedDateMillis	timestamp in UTC milliseconds from the epoch that represents an initial selection of a date. Provide a `null` to indicate no selection. Note that the state's `DatePickerState.selectedDateMillis` will provide a timestamp that represents the start of the day, which may be different than the provided initialSelectedDateMillis.
initialDisplayedMonthMillis	timestamp in UTC milliseconds from the epoch that represents an initial selection of a month to be displayed to the user. 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 DatePickerState(
    locale: CalendarLocale,
    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 most cases, you are advised to use the rememberDatePickerState 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.
initialSelectedDate	a `LocalDate` that represents an initial selection of a 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. 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),
            )
        }
    }
}