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

A date-time range picker in a bottom sheet — start/end tabs, calendar, time controls, draft editing with Save / Cancel and an inline clear button.

## Installation

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

Installs `day-picker` (calendar), `mini-calendar`, `action-sheet`, `button`, `label` and `docyrus-icon` as registry dependencies.

## Usage

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

const [start, setStart] = useState<Date | null>(null);
const [end, setEnd] = useState<Date | null>(null);

<DateTimeRangePicker
  label="Meeting"
  startDate={start}
  endDate={end}
  onChange={(s, e) => {
    setStart(s);
    setEnd(e);
  }}
/>
```

### Draft editing

Opening the sheet copies the committed range into a draft. Day taps and time changes only edit the draft. **Save** calls `onChange(start, end)` (an end before the start is clamped to the start); **Cancel**, the backdrop and swiping the sheet away discard the draft.

### Fixed duration

```tsx

```

With `defaultDuration` every change of the start day or time moves the end to `start + N minutes`. The end tab stays editable.

### Clearing

While a value is set, `clearable` (default `true`) shows an inline "x" on the trigger that immediately calls `onChange(null, null)`.

### 12-hour clock

```tsx

```

When `use24HourFormat` is omitted and a `<DateFormatProvider>` (e.g. `DocyrusTenantProvider`) is mounted, the trigger uses the tenant's `formatDateTime` / `formatTime`; otherwise it renders 24-hour times.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `startDate` | `Date \| null` | — | Committed range start. |
| `endDate` | `Date \| null` | — | Committed range end. |
| `onChange` | `(start: Date \| null, end: Date \| null) => void` | — | Called on Save (with the draft) and on clear (`null, null`). |
| `minDate` | `Date` | — | Minimum selectable date. The end tab additionally can't go before the draft start day. |
| `maxDate` | `Date` | — | Maximum selectable date. |
| `minuteInterval` | `number` | `5` | Minute step of the time controls (the seed time is rounded to it). |
| `disabled` | `boolean` | `false` | Disables the trigger and hides the clear button. |
| `placeholder` | `string` | `messages.placeholder` | Trigger text while empty. |
| `label` | `string` | — | Optional label rendered above the trigger. |
| `use24HourFormat` | `boolean` | — | `true` = 24-hour, `false` = 12-hour with an AM/PM toggle. Omitted → `DateFormatProvider` for the trigger, 24-hour controls. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'default'` | `'md'` | Trigger and label size (`'default'` is the web alias of `'md'`). |
| `defaultDuration` | `number` | — | Keep the end at `start + N` minutes whenever the start changes. |
| `clearable` | `boolean` | `true` | Show the inline clear "x" on the trigger while a value is set. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` | First day of the calendar week. |
| `messages` | `Partial<DateTimeRangePickerMessages>` | — | App-supplied copy; wins over `<UiTranslationProvider>`. |
| `className` | `string` | — | Additional CSS classes for the wrapper. |
| `style` | `ViewStyle` | — | Wrapper style. |

### DateTimeRangePickerMessages

Every key falls back to `t('ui.dateTimeRangePicker.<key>', …)` — `placeholder`, `clear`, `start`, `end`, `cancel` and `save` are the same keys the web component uses.

| Key | Fallback | Description |
|-----|----------|-------------|
| `placeholder` | `'Pick a date & time range'` | Trigger text while empty |
| `clear` | `'Clear'` | Accessibility label of the inline clear button |
| `title` | `'Date & Time Range'` | Sheet title |
| `start` | `'Start'` | Start tab |
| `end` | `'End'` | End tab |
| `startTime` | `'Start Time'` | Time section heading (start tab) |
| `endTime` | `'End Time'` | Time section heading (end tab) |
| `cancel` | `'Cancel'` | Discards the draft |
| `save` | `'Save'` | Commits the draft |
| `endBeforeStart` | `'End date must be after start date'` | Warning while the draft end is before the start |
| `am` | `'AM'` | AM toggle (12-hour mode) |
| `pm` | `'PM'` | PM toggle (12-hour mode) |

## Components

| Component | Description |
|-----------|-------------|
| `DateTimeRangePicker` | Trigger + range editing sheet |

## Type Exports

| Type | Description |
|------|-------------|
| `DateTimeRangePickerProps` | Props for the DateTimeRangePicker component |
| `DateTimeRangePickerSize` | `'sm' \| 'md' \| 'lg' \| 'default'` |
| `DateTimeRangePickerMessages` | App-supplied copy |

## Differences from web

The web component is bound to react-hook-form (`form`, `startField`, `endField`); native is value-based (`startDate` / `endDate` / `onChange`). Web always renders its `label` (default `'Date & Time Range'`); native renders it only when provided. `minuteInterval`, `minDate`, `maxDate` and `weekStartsOn` are native-only.

## Migration (breaking)

- The sheet's **Done** button is now **Save**, and a **Cancel** button discards the draft; the in-sheet **Clear** button was replaced by the trigger's inline "x" (`clearable`).
- The empty trigger text changed from `Select range` to `Pick a date & time range` (`messages.placeholder` / `placeholder`).
- The trigger now uses the shared control styling (`size`) and 24-hour times by default (it used to always print 12-hour `h:mm AM`).
- Presentation moved from a React Native `Modal` to the shared `ActionSheet`.