# rn-date-time-picker
URL: /docs/native/docyrus/date-time-picker

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

## Installation

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

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@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

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

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

### Date only

```tsx

```

### Time only

```tsx

```

### Controlled visibility (for embedding in forms)

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

```

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

### Label and 12-hour clock

```tsx

```

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.