{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

DatePickerKt

public final class DatePickerKt


Summary

Public methods

static final void
@ExperimentalMaterial3Api
@Composable
DatePicker(
    @NonNull DatePickerState state,
    @NonNull Modifier modifier,
    @NonNull DatePickerFormatter dateFormatter,
    @Composable Function0<Unit> title,
    @Composable Function0<Unit> headline,
    boolean showModeToggle,
    @NonNull DatePickerColors colors
)

Material Design date picker.

static final @NonNull DatePickerState
@ExperimentalMaterial3Api
DatePickerState(
    @NonNull CalendarLocale locale,
    Long initialSelectedDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

Creates a DatePickerState.

static final @NonNull DatePickerState
@Composable
@ExperimentalMaterial3Api
rememberDatePickerState(
    Long initialSelectedDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

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

Public methods

DatePicker

@ExperimentalMaterial3Api
@Composable
public static final void DatePicker(
    @NonNull DatePickerState state,
    @NonNull Modifier modifier,
    @NonNull DatePickerFormatter dateFormatter,
    @Composable Function0<Unit> title,
    @Composable Function0<Unit> headline,
    boolean showModeToggle,
    @NonNull DatePickerColors colors
)

Material Design date picker.

Date pickers let people select a date and preferably should be embedded into Dialogs. See DatePickerDialog.

By default, a date picker lets you pick a date via a calendar UI. However, it also allows switching into a date input mode for a manual entry of dates using the numbers on a keyboard.

Date picker image

A simple DatePicker looks like:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.DatePicker
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
    // Pre-select a date for January 4, 2020
    val datePickerState = rememberDatePickerState(initialSelectedDateMillis = 1578096000000)
    DatePicker(state = datePickerState, modifier = Modifier.padding(16.dp))

    Text(
        "Selected date timestamp: ${datePickerState.selectedDateMillis ?: "no selection"}",
        modifier = Modifier.align(Alignment.CenterHorizontally)
    )
}

A DatePicker with an initial UI of a date input mode looks like:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DisplayMode
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
    val state = rememberDatePickerState(initialDisplayMode = DisplayMode.Input)
    DatePicker(state = state, modifier = Modifier.padding(16.dp))

    Text(
        "Entered date timestamp: ${state.selectedDateMillis ?: "no input"}",
        modifier = Modifier.align(Alignment.CenterHorizontally)
    )
}

A DatePicker with a provided SelectableDates that blocks certain days from being selected looks like:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.material3.DatePicker
import androidx.compose.material3.SelectableDates
import androidx.compose.material3.Text
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

val datePickerState = rememberDatePickerState(
    selectableDates = object : SelectableDates {
        // Blocks Sunday and Saturday from being selected.
        override fun isSelectableDate(utcTimeMillis: Long): Boolean {
            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
                val dayOfWeek = Instant.ofEpochMilli(utcTimeMillis).atZone(ZoneId.of("UTC"))
                    .toLocalDate().dayOfWeek
                dayOfWeek != DayOfWeek.SUNDAY && dayOfWeek != DayOfWeek.SATURDAY
            } else {
                val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))
                calendar.timeInMillis = utcTimeMillis
                calendar[Calendar.DAY_OF_WEEK] != Calendar.SUNDAY &&
                    calendar[Calendar.DAY_OF_WEEK] != Calendar.SATURDAY
            }
        }

        // Allow selecting dates from year 2023 forward.
        override fun isSelectableYear(year: Int): Boolean {
            return year > 2022
        }
    }
)

Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
    DatePicker(state = datePickerState)
    Text(
        "Selected date timestamp: ${datePickerState.selectedDateMillis ?: "no selection"}",
        modifier = Modifier.align(Alignment.CenterHorizontally)
    )
}
Parameters
@NonNull DatePickerState state

state of the date picker. See rememberDatePickerState.

@NonNull Modifier modifier

the Modifier to be applied to this date picker

@NonNull DatePickerFormatter dateFormatter

a DatePickerFormatter that provides formatting skeletons for dates display

@Composable Function0<Unit> title

the title to be displayed in the date picker

@Composable Function0<Unit> headline

the headline to be displayed in the date picker

boolean showModeToggle

indicates if this DatePicker should show a mode toggle action that transforms it into a date input

@NonNull DatePickerColors colors

DatePickerColors that will be used to resolve the colors used for this date picker in different states. See DatePickerDefaults.colors.

DatePickerState

@ExperimentalMaterial3Api
public static final @NonNull DatePickerState DatePickerState(
    @NonNull CalendarLocale locale,
    Long initialSelectedDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

Creates a DatePickerState.

Note that in most cases, you are advised to use the rememberDatePickerState when in a composition.

Parameters
@NonNull CalendarLocale locale

a CalendarLocale to be used when formatting dates, determining the input format, and more

Long 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.

Long 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.

@NonNull IntRange yearRange

an IntRange that holds the year range that the date picker will be limited to

@NonNull DisplayMode initialDisplayMode

an initial DisplayMode that this state will hold

@NonNull SelectableDates 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.

Throws
kotlin.IllegalArgumentException

if the initial selected date or displayed month represent a year that is out of the year range.

rememberDatePickerState

@Composable
@ExperimentalMaterial3Api
public static final @NonNull DatePickerState rememberDatePickerState(
    Long initialSelectedDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

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

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

Parameters
Long initialSelectedDateMillis

timestamp in UTC milliseconds from the epoch that represents an initial selection of a date. Provide a null to indicate no selection.

Long 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.

@NonNull IntRange yearRange

an IntRange that holds the year range that the date picker will be limited to

@NonNull DisplayMode initialDisplayMode

an initial DisplayMode that this state will hold

@NonNull SelectableDates 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.