# React Native Date Time Picker

> React Native date and time picker in one component: one row of wheels on iOS, or a calendar with the time under it (Material) or beside it (web). Zero native code.

# DateTimePicker

`DateTimePicker` is a React Native date and time picker: pick a day and a time in one control. It has two displays, and each [design](../guides/designs) has its own default:

- **`wheel`** (the iOS default): one row of wheels like the iOS date-and-time picker. The day wheel shows `Today`, `Tue, Oct 27`… next to the hour, minute and AM/PM wheels.
- **`calendar`** (the Material and web default): a month grid and the time: hour and minute fields to type into under it in Material, wheels under it on iOS, and on the web columns to click beside it. `timePosition="below"` puts the time under the calendar instead, and `"beside"` puts it next to the calendar in any design when there's room for both. `timeDisplay` picks how the time is chosen in any design: `'wheel'`, `'dial'`, `'input'` or `'list'`.

```tsx
import { DateTimePicker } from 'patine-ui';
```

```tsx live wide
import { useState } from 'react';
import { Text } from 'react-native';
import { DateTimePicker } from 'patine-ui';

export default function Example() {
  const [date, setDate] = useState(new Date());
  return (
    <>
      <DateTimePicker value={date} onValueChange={setDate} minuteInterval={5} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {date.toLocaleString()}
      </Text>
    </>
  );
}
```

## Example: schedule a campaign

An email tool's Schedule step: the send can go out from the next quarter hour up to a month ahead, and the button says exactly when.

```tsx live wide
import { useState } from 'react';
import { Button, DateTimePicker, Text, VStack, addDays, formatDate } from 'patine-ui';

const now = new Date();
const earliest = new Date(Math.ceil(+now / 9e5) * 9e5);
const tomorrowAtNine = () => {
  const date = addDays(now, 1);
  date.setHours(9, 0, 0, 0);
  return date;
};

export default function Example() {
  const [sendAt, setSendAt] = useState(tomorrowAtNine);
  const when = formatDate(sendAt, 'en-US', { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' });
  return (
    <VStack gap="md">
      <VStack gap="xs">
        <Text weight="semibold">Winter sale: early access</Text>
        <Text size="sm" color="textSecondary">To 12,480 subscribers in “Loyal customers”</Text>
      </VStack>
      <DateTimePicker value={sendAt} onValueChange={setSendAt} minDate={earliest} maxDate={addDays(now, 30)} minuteInterval={15} />
      <Button>{`Schedule for ${when}`}</Button>
    </VStack>
  );
}
```

## Calendar display

```tsx live wide
import { useState } from 'react';
import { DateTimePicker } from 'patine-ui';

export default function Example() {
  const [date, setDate] = useState(new Date());
  return (
    <DateTimePicker
      display="calendar"
      value={date}
      onValueChange={setDate}
      minuteInterval={15}
    />
  );
}
```

Pass Calendar options (`markedDates`, `isDateDisabled`, `firstDayOfWeek`…) through `calendarProps`. Under the calendar, time wheels show 3 rows to keep the control short (the web's time columns show 5, and 9 beside the calendar); change that with `visibleItems`.

## Min and max

`minDate` and `maxDate` are **moments**, so their time counts too. The day wheel lists only the days between them. On the first day, times before `minDate` are disabled; on the last day, times after `maxDate` are disabled. A change that lands outside the range is pulled back to the nearest bound.

```tsx live wide
import { useState } from 'react';
import { Text } from 'react-native';
import { DateTimePicker, addDays } from 'patine-ui';

export default function Example() {
  const now = new Date();
  const [date, setDate] = useState(now);
  return (
    <>
      <Text style={{ textAlign: 'center', marginBottom: 8, color: '#6E685E' }}>
        From now, up to 2 weeks ahead
      </Text>
      <DateTimePicker
        value={date}
        onValueChange={setDate}
        minDate={now}
        maxDate={addDays(now, 14)}
        minuteInterval={15}
      />
    </>
  );
}
```

Without `minDate` / `maxDate`, the day wheel lists a year either side of today. If `value` is outside that span, the wheel stretches to include it. For dates further away, such as a birthday, pass `minDate` / `maxDate` or use [`DatePicker`](./date-picker).

## Day labels

Today reads `Today` (from `Intl.RelativeTimeFormat`, so it's translated); other days use the locale's short weekday, month and day. Write your own labels with `formatDay`:

```tsx
<DateTimePicker value={date} onValueChange={setDate} formatDay={(d) => d.toLocaleDateString('en-GB', { day: 'numeric', month: 'short' })} />
```

## In a sheet

```tsx
import { DateTimePickerSheet } from 'patine-ui';

<DateTimePickerSheet open={open} onOpenChange={setOpen} title="Reminder" value={date} onConfirm={setDate} minDate={new Date()} />
```

It takes the same props as `DateTimePicker` except `defaultValue` and `onValueChange`, plus the [shared sheet props](./picker-sheets#shared-props) and `onConfirm(date)`. The picked value is only reported when the user taps **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

## In a form field

`DateTimePickerField` opens the same sheet from a field, and shows the confirmed moment (`Oct 26, 2026, 9:30 AM`). Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

→ [Picker fields](./picker-fields)

## Props

All [TimePicker](./time-picker#props) wheel options apply too: `format`, `minuteInterval`, `showSeconds`, `secondInterval`, `loop`, `padHours`, `dayPeriodLabels`, `dayPeriodFirst`, `separator`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected date and time (controlled). |
| `defaultValue` | `Date` | now | Initial value when uncontrolled. |
| `onValueChange` | `(date: Date) => void` | — | Fires when the user picks a day or a time (a wheel settles, a day or time is tapped, a time is typed). Receives a **new** `Date`. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick while scrolling (haptics). |
| `display` | `'wheel' \| 'calendar'` | `'wheel'` on iOS, `'calendar'` in Material and on the web | One row of wheels, or a calendar with the time. |
| `timePosition` | `'beside' \| 'below'` | `'beside'` on the web, `'below'` in iOS and Material | Calendar display: the time beside the calendar or under it. Beside moves under the calendar when there is no room for both. |
| `timeDisplay` | `'wheel' \| 'dial' \| 'input' \| 'list'` | wheels in iOS, `'input'` in Material, `'list'` on the web | Calendar display: how the time is picked. `'dial'` and `'input'` fall back to wheels with `showSeconds`. |
| `minDate` | `Date` | — | Earliest selectable moment. |
| `maxDate` | `Date` | — | Latest selectable moment. |
| `locale` | `string` | device | BCP 47 locale for day labels, clock format and the calendar. |
| `formatDay` | `(date: Date, locale?: string) => string` | `Today`, `Tue, Oct 27` | Day wheel labels (wheel display). |
| `calendarProps` | `Omit<CalendarBaseProps, 'locale' \| 'minDate' \| 'maxDate' \| 'theme' \| 'testID'>` | — | Passed to the [Calendar](./date-picker#calendar) (calendar display). `locale`, `minDate`, `maxDate`, `theme` and `testID` come from the picker. |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` (wheel); with the calendar `3` wheels or `5` web rows under it, `9` beside it | Visible rows. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots) of the wheels. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow, over the provider's: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | Test ID. The wheels get `${testID}-day`, `-hour`, `-minute`… (in the calendar display: `-calendar`, `-time-hour`…). |

## Related

- [DatePicker](./date-picker): the calendar on its own
- [TimePicker](./time-picker): the time on its own
- [Picker fields](./picker-fields): a field that opens the picker in a sheet
