---
title: "DatePickerState"
description: "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`."
type: "function"
---
Function
Common
```kotlin
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. |
JvmAndAndroid
```kotlin
@RequiresApi(26)
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.
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.
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. |
| 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
### DatePickerCustomLocaleApi26Sample
```kotlin
@RequiresApi(Build.VERSION_CODES.O)
@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),
)
}
}
}
```
### DatePickerCustomLocaleSample
```kotlin
@RequiresApi(Build.VERSION_CODES.N)
@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),
)
}
}
}
```