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

DateRangePickerKt

public final class DateRangePickerKt


Summary

Public methods

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

Material Design date range picker.

static final @NonNull DateRangePickerState
@ExperimentalMaterial3Api
DateRangePickerState(
    @NonNull CalendarLocale locale,
    Long initialSelectedStartDateMillis,
    Long initialSelectedEndDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

Creates a DateRangePickerState.

static final @NonNull DateRangePickerState
@Composable
@ExperimentalMaterial3Api
rememberDateRangePickerState(
    Long initialSelectedStartDateMillis,
    Long initialSelectedEndDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

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

Public methods

DateRangePicker

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

Material Design date range picker.

Date range pickers let people select a range of dates and can be embedded into Dialogs.

Date range picker image

A simple DateRangePicker looks like:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.Icon
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Close
import androidx.compose.material3.DateRangePicker
import androidx.compose.material3.IconButton
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDateRangePickerState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.zIndex

// Decoupled snackbar host state from scaffold state for demo purposes.
val snackState = remember { SnackbarHostState() }
val snackScope = rememberCoroutineScope()
SnackbarHost(hostState = snackState, Modifier.zIndex(1f))

val state = rememberDateRangePickerState()
Column(modifier = Modifier.fillMaxSize(), verticalArrangement = Arrangement.Top) {
    // Add a row with "Save" and dismiss actions.
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .padding(start = 12.dp, end = 12.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.SpaceBetween
    ) {
        IconButton(onClick = { /* dismiss the UI */ }) {
            Icon(Icons.Filled.Close, contentDescription = "Localized description")
        }
        TextButton(
            onClick = {
                snackScope.launch {
                    snackState.showSnackbar(
                        "Saved range (timestamps): " +
                            "${state.selectedStartDateMillis!!..state.selectedEndDateMillis!!}"
                    )
                }
            },
            enabled = state.selectedEndDateMillis != null
        ) {
            Text(text = "Save")
        }
    }

    DateRangePicker(state = state, modifier = Modifier.weight(1f))
}
Parameters
@NonNull DateRangePickerState state

state of the date range picker. See rememberDateRangePickerState.

@NonNull Modifier modifier

the Modifier to be applied to this date range 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 range picker

@Composable Function0<Unit> headline

the headline to be displayed in the date range picker

boolean showModeToggle

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

@NonNull DatePickerColors colors

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

DateRangePickerState

@ExperimentalMaterial3Api
public static final @NonNull DateRangePickerState DateRangePickerState(
    @NonNull CalendarLocale locale,
    Long initialSelectedStartDateMillis,
    Long initialSelectedEndDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

Creates a DateRangePickerState.

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

Parameters
@NonNull CalendarLocale locale

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

Long initialSelectedStartDateMillis

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

Long initialSelectedEndDateMillis

timestamp in UTC milliseconds from the epoch that represents an initial selection of an end 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 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.

@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 timestamps do not fall within the year range this state is created with, or the end date precedes the start date, or when an end date is provided without a start date (e.g. the start date was null, while the end date was not).

rememberDateRangePickerState

@Composable
@ExperimentalMaterial3Api
public static final @NonNull DateRangePickerState rememberDateRangePickerState(
    Long initialSelectedStartDateMillis,
    Long initialSelectedEndDateMillis,
    Long initialDisplayedMonthMillis,
    @NonNull IntRange yearRange,
    @NonNull DisplayMode initialDisplayMode,
    @NonNull SelectableDates selectableDates
)

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

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

Long initialSelectedEndDateMillis

timestamp in UTC milliseconds from the epoch that represents an initial selection of an end 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 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.

@NonNull IntRange yearRange

an IntRange that holds the year range that the date range 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.