Reference version

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

DateTimePicker

Jetpack Compose components for selecting dates, date ranges, and times.

Android
Included in Expo Go
Recommended version:
~58.0.1

Expo UI's date and time picker components match the official Jetpack Compose Date Picker, Date Range Picker, and Time Picker APIs.

Material 3 date picker showing a selected date in a calendar gridMaterial 3 date picker showing a selected date in a calendar grid

Installation

Terminal
npx expo install @expo/ui
yarn expo install @expo/ui
pnpm expo install @expo/ui
bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Date picker

DatePickerExample.tsx
import { useState } from 'react'; import { Host, DateTimePicker } from '@expo/ui/jetpack-compose'; export default function DatePickerExample() { const [selectedDate, setSelectedDate] = useState(new Date()); return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <DateTimePicker onDateSelected={date => { setSelectedDate(date); }} displayedComponents="date" initialDate={selectedDate.toISOString()} variant="picker" /> </Host> ); }

Time picker

TimePickerExample.tsx
import { useState } from 'react'; import { Host, DateTimePicker } from '@expo/ui/jetpack-compose'; export default function TimePickerExample() { const [selectedDate, setSelectedDate] = useState(new Date()); return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <DateTimePicker onDateSelected={date => { setSelectedDate(date); }} displayedComponents="hourAndMinute" initialDate={selectedDate.toISOString()} variant="picker" /> </Host> ); }

Input variant

Use variant="input" to display the picker as a text input field instead of the default picker UI.

InputVariantExample.tsx
import { useState } from 'react'; import { Host, DateTimePicker } from '@expo/ui/jetpack-compose'; export default function InputVariantExample() { const [selectedDate, setSelectedDate] = useState(new Date()); return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <DateTimePicker onDateSelected={date => { setSelectedDate(date); }} displayedComponents="date" initialDate={selectedDate.toISOString()} variant="input" /> </Host> ); }

Date range picker

DateRangePickerAndroidExample.tsx
import { useState } from 'react'; import { DateRangePicker, type DateRangeSelection, Host, } from '@expo/ui/jetpack-compose'; export default function DateRangePickerAndroidExample() { const [range, setRange] = useState<DateRangeSelection>({ start: new Date(), end: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000), }); return ( <Host style={{ flex: 1 }}> <DateRangePicker initialStartDate={range.start?.toISOString()} initialEndDate={range.end?.toISOString()} onDateRangeSelected={setRange} /> </Host> ); }

The callback's end value is null until the user finishes selecting the range.

Date range picker dialog

DateRangePickerDialogExample.tsx
import { useState } from 'react'; import { Button } from 'react-native'; import { DateRangePickerDialog, type DateRangeSelection, Host, } from '@expo/ui/jetpack-compose'; export default function DateRangePickerDialogExample() { const [visible, setVisible] = useState(false); const [range, setRange] = useState<DateRangeSelection>({ start: null, end: null, }); return ( <> <Button title="Select dates" onPress={() => setVisible(true)} /> {visible && ( <Host> <DateRangePickerDialog initialStartDate={range.start?.toISOString()} initialEndDate={range.end?.toISOString()} onDateRangeSelected={selectedRange => { setRange(selectedRange); setVisible(false); }} onDismissRequest={() => setVisible(false)} /> </Host> )} </> ); }

API

import { DateRangePicker, DateRangePickerDialog, DateTimePicker, } from '@expo/ui/jetpack-compose';

Components

DatePickerDialog

Android

Type: React.Element<DatePickerDialogProps>

DatePickerDialogProps

color

Android
Optional • Type: ColorValue

confirmButtonLabel

Android
Optional • Type: string

dismissButtonLabel

Android
Optional • Type: string

elementColors

Android

initialDate

Android
Optional • Literal type: union

The initially selected date. When omitted, the dialog opens on the current month with no selection and the confirm button stays disabled until a date is picked.

Acceptable values are: string | null

onDateSelected

Android
Optional • Type: (date: Date) => void

onDismissRequest

Android
Type: () => void

selectableDates

Android
Optional • Type: { end: Date, start: Date }

showVariantToggle

Android
Optional • Type: boolean

variant

Android
Optional • Type: AndroidVariant

DateRangePicker

Android

Type: React.Element<DateRangePickerProps>

Renders an inline Material 3 date range picker.

DateRangePickerProps

color

Android
Optional • Type: ColorValue

The tint color to use on the picker elements.

elementColors

Android
Optional • Type: DatePickerElementColors

Fine-grained color overrides for individual picker elements.

initialEndDate

Android
Optional • Literal type: union

The initially selected end date, as an ISO 8601 string. It must be on or after initialStartDate.

Acceptable values are: string | null

initialStartDate

Android
Optional • Literal type: union

The initially selected start date, as an ISO 8601 string.

Acceptable values are: string | null

modifiers

Android
Optional • Type: ModifierConfig[]

Modifiers for the component.

onDateRangeSelected

Android
Optional • Type: (range: DateRangeSelection) => void

Called once when the component mounts with the initial range, and again whenever the selected date range changes. The end date is null while the user is selecting a range.

selectableDates

Android
Optional • Type: { end: Date, start: Date }

Constrains which dates can be selected. start is the earliest selectable date and end is the latest.

showVariantToggle

Android
Optional • Type: boolean • Default: true

Show a button to toggle between variants on Android.

variant

Android
Optional • Type: AndroidVariant • Default: 'picker'

The variant of the picker, which determines its appearance and behavior.

DateRangePickerDialog

Android

Type: React.Element<DateRangePickerDialogProps>

Renders a modal Material 3 date range picker.

DateRangePickerDialogProps

color

Android
Optional • Type: ColorValue

The tint color to use on the picker elements and dialog buttons.

confirmButtonLabel

Android
Optional • Type: string

The label for the button that confirms the selected range. Defaults to the system "Ok" string.

dismissButtonLabel

Android
Optional • Type: string

The label for the button that dismisses the dialog. Defaults to the system "Cancel" string.

onDateRangeSelected

Android
Optional • Type: (range: DateRangeSelection) => void

Callback function that is called when the user confirms a complete date range.

onDismissRequest

Android
Type: () => void

Callback function that is called when the dialog is dismissed.

Inherited props

DateTimePicker

Android

Type: React.Element<DateTimePickerProps>

Renders an inline DateTimePicker component.

DateTimePickerProps

color

Android
Optional • Type: ColorValue

The tint color to use on the picker elements. When elementColors is not provided, this color is applied to a subset of picker elements (selected day, title, headline, today border for date picker; selector, selected time segment, clock dial for time picker).

displayedComponents

Android
Optional • Type: DisplayedComponents • Default: 'date'

The components that the picker should display. On Android, you can have a picker that selects just the date or just the time. dateAndTime is only available on iOS and will result in a date picker on Android. On iOS, you can have a picker that selects both date and time.

elementColors

Android

Fine-grained color overrides for individual picker elements. When provided, these take precedence over the color prop. Date picker color keys are used when displayedComponents is 'date' or 'dateAndTime'. Time picker color keys are used when displayedComponents is 'hourAndMinute'. Unset values fall back to Material 3 theme defaults.

initialDate

Android
Optional • Literal type: union

The initial date to display on the picker.

Acceptable values are: string | null

is24Hour

Android
Optional • Type: boolean • Default: true

Determines what format the clock should be displayed in on Android.

modifiers

Android
Optional • Type: ModifierConfig[]

Modifiers for the component.

onDateSelected

Android
Optional • Type: (date: Date) => void

Callback function that is called when a date is selected.

selectableDates

Android
Optional • Type: { end: Date, start: Date }

Constrains which dates can be selected. Mirrors the native Compose selectableDates parameter. start is the earliest selectable date, end is the latest.

showVariantToggle

Android
Optional • Type: boolean • Default: true

Show a button to toggle between variants on Android.

variant

Android
Optional • Type: AndroidVariant • Default: 'picker'

The variant of the picker, which determines its appearance and behavior.

TimePickerDialog

Android

Type: React.Element<TimePickerDialogProps>

TimePickerDialogProps

color

Android
Optional • Type: ColorValue

confirmButtonLabel

Android
Optional • Type: string

dismissButtonLabel

Android
Optional • Type: string

elementColors

Android

initialDate

Android
Optional • Literal type: union

Acceptable values are: string | null

is24Hour

Android
Optional • Type: boolean

onDateSelected

Android
Optional • Type: (date: Date) => void

onDismissRequest

Android
Type: () => void

Types

AndroidVariant

Android

Literal type: string

Acceptable values are: 'picker' | 'input'

DatePickerElementColors

Android

Color overrides for the Material 3 DatePicker component. All properties are optional — unset values use Material 3 theme defaults.

PropertyTypeDescription
containerColor(optional)ColorValue

The background color of the date picker.

currentYearContentColor(optional)ColorValue

The color used for the current year content.

dayContentColor(optional)ColorValue

The color used for day content (number text).

dayInSelectionRangeContainerColor(optional)ColorValue

The container color for days within a date range selection.

dayInSelectionRangeContentColor(optional)ColorValue

The content color for days within a date range selection.

disabledDayContentColor(optional)ColorValue

The color used for disabled day content.

disabledSelectedDayContainerColor(optional)ColorValue

The color used for a disabled selected day container.

disabledSelectedDayContentColor(optional)ColorValue

The color used for a disabled selected day content.

disabledSelectedYearContainerColor(optional)ColorValue

The color used for a disabled selected year container.

disabledSelectedYearContentColor(optional)ColorValue

The color used for a disabled selected year content.

disabledYearContentColor(optional)ColorValue

The color used for disabled year item content.

dividerColor(optional)ColorValue

The color used for divider lines.

headlineContentColor(optional)ColorValue

The color used for the date picker's headline.

navigationContentColor(optional)ColorValue

The color used for navigation arrows and year selection menu button.

selectedDayContainerColor(optional)ColorValue

The color used for the selected day container/background circle.

selectedDayContentColor(optional)ColorValue

The color used for selected day content.

selectedYearContainerColor(optional)ColorValue

The color used for the selected year container/background.

selectedYearContentColor(optional)ColorValue

The color used for the selected year content.

subheadContentColor(optional)ColorValue

The color used for the month and year subhead labels.

titleContentColor(optional)ColorValue

The color used for the date picker's title.

todayContentColor(optional)ColorValue

The color used for today's date text.

todayDateBorderColor(optional)ColorValue

The color used for today's date border.

weekdayContentColor(optional)ColorValue

The color used for the weekday letters (Mon, Tue, etc.).

yearContentColor(optional)ColorValue

The color used for year item content.

DateRangeSelection

Android

The date range reported by DateRangePicker and DateRangePickerDialog.

PropertyTypeDescription
endDate | null

The selected end date, or null until the user selects the second date of the range.

startDate | null

The selected start date, or null when no start date is selected.

DisplayedComponents

Android

Literal type: string

Acceptable values are: 'date' | 'hourAndMinute' | 'dateAndTime'

TimePickerElementColors

Android

Color overrides for the Material 3 TimePicker component. All properties are optional — unset values use Material 3 theme defaults.

PropertyTypeDescription
clockDialColor(optional)ColorValue

The background color of the clock dial.

clockDialSelectedContentColor(optional)ColorValue

The color of clock dial numbers when selected or overlapping the selector.

clockDialUnselectedContentColor(optional)ColorValue

The color of clock dial numbers when unselected.

containerColor(optional)ColorValue

The container/background color of the time picker.

periodSelectorBorderColor(optional)ColorValue

The border color of the AM/PM period selector.

periodSelectorSelectedContainerColor(optional)ColorValue

The background color of the selected AM/PM period.

periodSelectorSelectedContentColor(optional)ColorValue

The text color of the selected AM/PM period.

periodSelectorUnselectedContainerColor(optional)ColorValue

The background color of the unselected AM/PM period.

periodSelectorUnselectedContentColor(optional)ColorValue

The text color of the unselected AM/PM period.

selectorColor(optional)ColorValue

The color of the clock dial selector (hand).

timeSelectorSelectedContainerColor(optional)ColorValue

The background color of the selected hour/minute segment.

timeSelectorSelectedContentColor(optional)ColorValue

The text color of the selected hour/minute segment.

timeSelectorUnselectedContainerColor(optional)ColorValue

The background color of the unselected hour/minute segment.

timeSelectorUnselectedContentColor(optional)ColorValue

The text color of the unselected hour/minute segment.