# DateRangePicker

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/DateRangePicker.composable#DateRangePicker(androidx.compose.material3.DateRangePickerState,androidx.compose.ui.Modifier,androidx.compose.material3.DatePickerFormatter,androidx.compose.material3.DatePickerColors,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.focus.FocusRequester)( state: https://developer.android.com/reference/kotlin/androidx/compose/material3/DateRangePickerState, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, dateFormatter: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter, colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors, title: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, headline: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, showModeToggle: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, focusRequester: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester? )` [Material Design date range picker](https://m3.material.io/components/date-pickers/overview) | Cmn |

## Functions

### DateRangePicker

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/DateRangePicker.kt+function:DateRangePicker)

```
@Composable
fun DateRangePicker(
    state: DateRangePickerState,
    modifier: Modifier = Modifier,
    dateFormatter: DatePickerFormatter = remember { DatePickerDefaults.dateFormatter() },
    colors: DatePickerColors = DatePickerDefaults.colors(),
    title: (@Composable () -> Unit)? = {
        DateRangePickerDefaults.DateRangePickerTitle(
            displayMode = state.displayMode,
            modifier = Modifier.padding(DateRangePickerTitlePadding),
            contentColor = colors.titleContentColor,
        )
    },
    headline: (@Composable () -> Unit)? = {
        DateRangePickerDefaults.DateRangePickerHeadline(
            selectedStartDateMillis = state.selectedStartDateMillis,
            selectedEndDateMillis = state.selectedEndDateMillis,
            displayMode = state.displayMode,
            dateFormatter,
            modifier = Modifier.padding(DateRangePickerHeadlinePadding),
            contentColor = colors.headlineContentColor,
        )
    },
    showModeToggle: Boolean = true,
    focusRequester: FocusRequester? = remember { FocusRequester() }
): Unit
```

[Material Design date range picker](https://m3.material.io/components/date-pickers/overview)

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

![Date range picker
image](https://developer.android.com/images/reference/androidx/compose/material3/range-picker.png)

A simple DateRangePicker looks like:

```kotlin
import androidx.compose.foundation.background
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.icons.Icons
import androidx.compose.material.icons.filled.Close
import androidx.compose.material3.Button
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDefaults
import androidx.compose.material3.DateRangePicker
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TooltipAnchorPosition
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberDateRangePickerState
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.LiveRegionMode
import androidx.compose.ui.semantics.liveRegion
import androidx.compose.ui.semantics.paneTitle
import androidx.compose.ui.semantics.semantics
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()
                .background(DatePickerDefaults.colors().containerColor)
                .padding(start = 12.dp, end = 12.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.SpaceBetween,
    ) {
        TooltipBox(
            positionProvider =
                TooltipDefaults.rememberTooltipPositionProvider(TooltipAnchorPosition.Above),
            tooltip = {
                PlainTooltip(
                    modifier =
                        Modifier.semantics {
                            // TODO(b/496338253): Remove this modifier once bug where tooltip
                            //  text is not announced by a11y screen readers is resolved.
                            liveRegion = LiveRegionMode.Assertive
                            paneTitle = "Close"
                        }
                ) {
                    Text("Close")
                }
            },
            state = rememberTooltipState(),
        ) {
            IconButton(onClick = { /* dismiss the UI */ }) {
                Icon(Icons.Filled.Close, contentDescription = "Close")
            }
        }
        TextButton(
            onClick = {
                snackScope.launch {
                    val range = state.selectedStartDateMillis!!..state.selectedEndDateMillis!!
                    snackState.showSnackbar("Saved range (timestamps): $range")
                }
            },
            enabled = state.selectedEndDateMillis != null,
        ) {
            Text(text = "Save")
        }
    }
    DateRangePicker(state = state, modifier = Modifier.weight(1f))
}
```

A DateRangePicker can also be initialized with Java Time APIs when running on Android with API 26 and above:

```kotlin
import androidx.compose.foundation.background
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.icons.Icons
import androidx.compose.material.icons.filled.Close
import androidx.compose.material3.Button
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDefaults
import androidx.compose.material3.DateRangePicker
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TooltipAnchorPosition
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.getSelectedEndDate
import androidx.compose.material3.getSelectedStartDate
import androidx.compose.material3.rememberDateRangePickerState
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.LiveRegionMode
import androidx.compose.ui.semantics.liveRegion
import androidx.compose.ui.semantics.paneTitle
import androidx.compose.ui.semantics.semantics
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))

// Creates a state with pre-selected date range.
val state =
    rememberDateRangePickerState(
        initialSelectedStartDate = LocalDate.of(2023, 4, 15),
        initialSelectedEndDate = LocalDate.of(2023, 4, 20),
    )
Column(modifier = Modifier.fillMaxSize(), verticalArrangement = Arrangement.Top) {
    // Add a row with "Save" and dismiss actions.
    Row(
        modifier =
            Modifier.fillMaxWidth()
                .background(DatePickerDefaults.colors().containerColor)
                .padding(start = 12.dp, end = 12.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.SpaceBetween,
    ) {
        TooltipBox(
            positionProvider =
                TooltipDefaults.rememberTooltipPositionProvider(TooltipAnchorPosition.Above),
            tooltip = {
                PlainTooltip(
                    modifier =
                        Modifier.semantics {
                            // TODO(b/496338253): Remove this modifier once bug where tooltip
                            //  text is not announced by a11y screen readers is resolved.
                            liveRegion = LiveRegionMode.Assertive
                            paneTitle = "Close"
                        }
                ) {
                    Text("Close")
                }
            },
            state = rememberTooltipState(),
        ) {
            IconButton(onClick = { /* dismiss the UI */ }) {
                Icon(Icons.Filled.Close, contentDescription = "Close")
            }
        }
        TextButton(
            onClick = {
                snackScope.launch {
                    val range = state.getSelectedStartDate()!!..state.getSelectedEndDate()!!
                    snackState.showSnackbar("Saved range: $range")
                }
            },
            enabled = state.getSelectedEndDate() != null,
        ) {
            Text(text = "Save")
        }
    }
    DateRangePicker(state = state, modifier = Modifier.weight(1f))
}
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/material3/DateRangePickerState` | state of the date range picker. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/rememberDateRangePickerState.composable#rememberDateRangePickerState(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.ranges.IntRange,androidx.compose.material3.DisplayMode,androidx.compose.material3.SelectableDates)`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to this date range picker |
| `dateFormatter: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter = remember { DatePickerDefaults.dateFormatter() }` | a `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerFormatter` that provides formatting skeletons for dates display |
| `colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors = DatePickerDefaults.colors()` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerColors` that will be used to resolve the colors used for this date range picker in different states. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/DatePickerDefaults#colors()`. |
| `title: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = { DateRangePickerDefaults.DateRangePickerTitle( displayMode = state.displayMode, modifier = Modifier.padding(DateRangePickerTitlePadding), contentColor = colors.titleContentColor, ) }` | the title to be displayed in the date range picker |
| `headline: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = { DateRangePickerDefaults.DateRangePickerHeadline( selectedStartDateMillis = state.selectedStartDateMillis, selectedEndDateMillis = state.selectedEndDateMillis, displayMode = state.displayMode, dateFormatter, modifier = Modifier.padding(DateRangePickerHeadlinePadding), contentColor = colors.headlineContentColor, ) }` | the headline to be displayed in the date range picker |
| `showModeToggle: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | indicates if this DateRangePicker should show a mode toggle action that transforms it into a date range input |
| `focusRequester: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester? = remember { FocusRequester() }` | a focus requester that will be used to focus the text field when the date picker is in an input mode. Pass `null` to not focus the text field if that's the desired behavior. |