DateTimePicker

A date and time picker using the native platform picker with ActionSheet presentation on iOS and dialog on Android.

iOSAndroid

Preview DateTimePicker on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-date-time-picker

Required Packages(1 package)

pnpm add @react-native-community/datetimepicker

The native picker is loaded via dynamic require() — the component renders a fallback message if the package is not installed.

Usage

import { DateTimePicker } from '@/components/docyrus-native/date-time-picker';

<DateTimePicker
  value={new Date()}
  onChange={(date) => console.log(date)}
  format="datetime"
/>

Date only

<DateTimePicker value={date} onChange={setDate} format="date" />

Time only

<DateTimePicker value={date} onChange={setDate} format="time" />

Controlled visibility (for embedding in forms)

const [open, setOpen] = useState(false);

<DateTimePicker
  value={date}
  onChange={setDate}
  format="date"
  open={open}
  onOpenChange={setOpen}
/>

When open and onOpenChange are provided, the built-in trigger button is not rendered — the parent controls visibility.

Label and 12-hour clock

<DateTimePicker label="Due date" value={date} onChange={setDate} use24HourFormat={false} />

When use24HourFormat is omitted and a <DateFormatProvider> (e.g. DocyrusTenantProvider) is mounted, the trigger uses the tenant's formatDate / formatTime / formatDateTime; otherwise it renders dd.MM.yyyy HH:mm.

API Reference

Prop	Type	Default	Description
`value`	`Date \| null`	—	The currently selected date/time value.
`onChange`	`(date: Date \| null) => void`	—	Fired when the user confirms (Done / Android dialog) or clears the selection.
`minDate`	`Date`	—	Minimum selectable date.
`maxDate`	`Date`	—	Maximum selectable date.
`disabled`	`boolean`	`false`	Disables the picker trigger.
`placeholder`	`string`	sheet title	Trigger text when no value is selected.
`format`	`'datetime' \| 'date' \| 'time'`	`'datetime'`	Picker mode.
`size`	`'sm' \| 'md' \| 'lg' \| 'default'`	`'md'`	Trigger size (`'default'` is the web alias of `'md'`). Also sizes the `label`.
`clearable`	`boolean`	`true`	Show the Clear button in the picker header.
`use24HourFormat`	`boolean`	—	`true` = 24-hour, `false` = 12-hour AM/PM trigger text. Omitted → `DateFormatProvider` when mounted, else 24-hour. Android's native dialog follows it (`is24Hour`); the iOS spinner follows the device clock.
`label`	`string`	—	Optional label rendered above the trigger (uncontrolled mode).
`messages`	`Partial<DateTimePickerMessages>`	—	App-supplied copy; wins over `<UiTranslationProvider>`.
`open`	`boolean`	—	Controlled visibility. When provided, no built-in trigger is rendered.
`onOpenChange`	`(open: boolean) => void`	—	Callback when picker visibility changes.
`className`	`string`	—	Additional class names for the trigger (or the label wrapper when `label` is set).
`style`	`ViewStyle`	—	Additional styles for the trigger (or the label wrapper).

DateTimePickerMessages

Every key falls back to t('ui.dateTimePicker.<key>', …).

Key	Fallback	Description
`selectDate`	`'Select Date'`	Sheet title for date mode.
`selectTime`	`'Select Time'`	Sheet title for time mode.
`selectDateTime`	`'Select Date & Time'`	Sheet title for datetime mode.
`cancel`	`'Cancel'`	Cancel button label.
`done`	`'Done'`	Done button label.
`clear`	`'Clear'`	Clear button label.
`fallback`	`'Install @react-native-community/datetimepicker for native picker'`	Shown when the native picker is not installed.

Platform Behavior

Platform	Presentation	Picker type
iOS	ActionSheet with spinner — changes are a draft until Done; dismissing discards	Native `UIDatePicker` (spinner mode)
Android	Native dialog; `datetime` runs a date dialog followed by a time dialog	`DatePickerDialog` / `TimePickerDialog`
No native picker	Inline fallback message	—

Exported Helpers

Export	Type	Description
`formatPickerDate`	`(date, mode, dateFormat?, timeFormat?) => string`	Format a date for display. `'short'` / `'medium'` render `dd.MM.yyyy HH:mm`; `'long'` / `'full'` use `Intl` with `timeFormat` (`'12h'` default). Used by form fields.

Components

Component	Description
`DateTimePicker`	Trigger + native date/time picker

Type Exports

Type	Description
`DateTimePickerProps`	Props for the DateTimePicker component.
`DateTimePickerFormat`	`'datetime' \| 'date' \| 'time'` — picker mode.
`DateTimePickerSize`	`'sm' \| 'md' \| 'lg' \| 'default'`
`DateTimePickerMessages`	App-supplied copy.
`DateTimeMinuteInterval`	`1 \| 5 \| 10 \| 15 \| 30`

Differences from web

The web DateTimePicker is bound to react-hook-form (form / field); native is value-based (value / onChange) and integrates with forms through form-fields. The web autoFocus (keyboard focus of the popover calendar) has no native equivalent.

DateTimePicker

On this page