# React Native Date, Time & Wheel Picker Fields

> Form fields for React Native that open a picker in a dropdown, bottom sheet or modal, or expand it inline under the field, and show the picked value, with error and helper text for forms: DatePickerField, TimePickerField, TimeRangePickerField, DateTimePickerField, DurationPickerField, MonthPickerField, ColorPickerField, WheelPickerField, EmojiPickerField and PickerField.

# Picker fields

In a form, a picker usually isn't on screen. The user taps a field, picks in a bottom sheet (a dropdown under the field on the web), and sees the value in the field once it closes. Each picker has a field that does this, with the same look as [`Select`](./select)'s field:

| Field | Opens | Shows |
| --- | --- | --- |
| `DatePickerField` | [`DatePickerSheet`](./picker-sheets#datepickersheet) | `Oct 5, 2026`, a range `Oct 5, 2026 – Oct 9, 2026` or a list of dates |
| `TimePickerField` | [`TimePickerSheet`](./picker-sheets#timepickersheet) | `9:30 AM` or `09:30`, following `format` and `locale` |
| `TimeRangePickerField` | [`TimeRangePickerSheet`](./time-range-picker#in-a-sheet-or-a-field) | `9:00 AM – 5:00 PM`, with ` +1` when it ends the next day |
| `DateTimePickerField` | [`DateTimePickerSheet`](./date-time-picker#in-a-sheet) | `Oct 26, 2026, 9:30 AM` |
| `DurationPickerField` | [`DurationPickerSheet`](./duration-picker#in-a-sheet) | `1 h 30 min` |
| `MonthPickerField` | [`MonthPickerSheet`](./month-picker#in-a-sheet) | `October 2026` |
| `ColorPickerField` | [`ColorPickerSheet`](./color-picker#in-a-sheet) | A swatch and `#E4572E` |
| `WheelPickerField` | [`WheelPickerSheet`](./picker-sheets#wheelpickersheet) | The selected item's `label` |
| `EmojiPickerField` | [`EmojiPickerSheet`](./picker-sheets#emojipickersheet) | `value`, the emoji you pass |
| `PickerField` | Any sheet you render | `displayValue` |

```tsx
import { DatePickerField, TimePickerField, DateTimePickerField, WheelPickerField, EmojiPickerField, PickerField } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import {
  DatePickerField,
  DateTimePickerField,
  EmojiPickerField,
  Select,
  TimePickerField,
  WheelPickerField,
} from 'patine-ui';
import type { DateRange } from 'patine-ui';

const guests = Array.from({ length: 8 }, (_, i) => ({
  label: `${i + 1} guest${i ? 's' : ''}`,
  value: i + 1,
}));
const rooms = ['Standard', 'Deluxe', 'Suite'].map((r) => ({
  label: r,
  value: r,
}));

export default function Example() {
  const [stay, setStay] = useState<DateRange>({ start: null, end: null });
  const [arrival, setArrival] = useState<Date | undefined>();
  const [guestCount, setGuestCount] = useState<number | undefined>();
  const [room, setRoom] = useState<string | null>(null);
  const [reminder, setReminder] = useState<Date | undefined>();
  const [mood, setMood] = useState<string | undefined>();
  return (
    <View style={{ gap: 14 }}>
      <DatePickerField
        label="Stay"
        placeholder="Add dates"
        mode="range"
        value={stay}
        onConfirm={setStay}
        minDate={new Date()}
      />
      <TimePickerField
        label="Arrival time"
        placeholder="Choose a time"
        value={arrival}
        onConfirm={setArrival}
        minuteInterval={15}
      />
      <WheelPickerField
        label="Guests"
        placeholder="How many?"
        items={guests}
        value={guestCount}
        onConfirm={setGuestCount}
      />
      <Select
        label="Room"
        placeholder="Choose a room"
        options={rooms}
        value={room}
        onValueChange={setRoom}
      />
      <DateTimePickerField
        label="Reminder"
        placeholder="Set a reminder"
        value={reminder}
        onConfirm={setReminder}
        clearable
        onClear={() => setReminder(undefined)}
      />
      <EmojiPickerField
        label="Mood"
        placeholder="Pick an emoji"
        value={mood}
        onSelect={setMood}
      />
    </View>
  );
}
```

Each field takes the props of the sheet it opens, without `open`, plus the [field props](#props). The field owns the open state; you keep the value. As with the sheets, `onConfirm` fires only on **Done**, so your state changes only when the user confirms (except `inline`, which has no **Done** and commits each change). On the web they open as dropdowns; switch `presentation` in the panel to see the same form with bottom sheets or modals.

## Example: log a run

A running app's Add activity form: each field shows its value in the app's format, opens the right picker, and the pace under them follows the distance and the time.

```tsx live
import { useState } from 'react';
import { Box, Button, DatePickerField, DurationPickerField, Text, TimePickerField, WheelPickerField, formatDate } from 'patine-ui';

const KM = Array.from({ length: 84 }, (_, i) => ({ label: `${((i + 1) / 2).toFixed(1)} km`, value: (i + 1) / 2 }));

export default function Example() {
  const today = new Date();
  const [day, setDay] = useState<Date | undefined>(today);
  const [start, setStart] = useState<Date | undefined>(new Date(today.getFullYear(), today.getMonth(), today.getDate(), 7, 15));
  const [distance, setDistance] = useState<number | undefined>(10);
  const [duration, setDuration] = useState<number | undefined>(52 * 60 + 30);
  const pace = distance && duration ? duration / distance : 0;
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 400 }}>
      <Text weight="semibold">Add a run</Text>
      <DatePickerField label="Day" value={day} onConfirm={setDay} maxDate={today} displayValue={day ? formatDate(day, undefined, { weekday: 'long', month: 'short', day: 'numeric' }) : undefined} />
      <TimePickerField label="Started at" value={start} onConfirm={setStart} minuteInterval={5} />
      <WheelPickerField label="Distance" items={KM} value={distance} onConfirm={setDistance} />
      <DurationPickerField label="Moving time" value={duration} onConfirm={setDuration} showSeconds />
      <Text color="textSecondary">
        Pace {pace ? `${Math.floor(pace / 60)}:${String(Math.round(pace % 60)).padStart(2, '0')} /km` : '—'}
      </Text>
      <Button disabled={!day || !distance || !duration}>Save run</Button>
    </Box>
  );
}
```

## Dropdown, bottom sheet, modal or inline

`presentation` sets where the picker opens:

| `presentation` | Opens |
| --- | --- |
| `'auto'` (default) | A dropdown on the web, a bottom sheet on native. |
| `'dropdown'` | Under the field, like a menu, or above it when there's more room there. **Cancel** and **Done** sit below the picker; a tap outside cancels. It's at least 320 px wide, so a calendar fits under a narrow field. It opens on the side with room for the whole picker; in a window too short for it, the dropdown scrolls. |
| `'bottomSheet'` | A bottom sheet with the title and buttons in its header. |
| `'modal'` | A centered dialog. |
| `'inline'` | In place, under the field: the picker expands down, pushing the content below it, and folds back up on a second tap on the field. There's no **Cancel** or **Done**: each change goes to `onConfirm` (or `onSelect`) right away, like the iOS Settings and Clock apps. A date range commits once both ends are picked. |

```tsx
<DatePickerField label="Stay" mode="range" value={stay} onConfirm={setStay} />
<DatePickerField label="Stay" mode="range" value={stay} onConfirm={setStay} presentation="dropdown" />
<DurationPickerField label="Snooze" value={snooze} onConfirm={setSnooze} presentation="inline" />
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { DurationPickerField, TimePickerField } from 'patine-ui';

export default function Example() {
  const [alarm, setAlarm] = useState(new Date(2026, 0, 1, 7, 30));
  const [snooze, setSnooze] = useState(9 * 60);
  return (
    <View style={{ gap: 16 }}>
      <TimePickerField label="Alarm" value={alarm} onConfirm={setAlarm} presentation="inline" />
      <DurationPickerField label="Snooze" value={snooze} onConfirm={setSnooze} showHours={false} presentation="inline" />
    </View>
  );
}
```

`sheetProps` and `title` apply to the bottom sheet and the modal; the dropdown and the inline picker have no header. With `renderTrigger`, `open()` toggles an inline picker, so your trigger collapses it too. [`Select`](./select#presentation) takes the same values and the same `'auto'` default.

## What the field shows

Dates and times are formatted with `Intl` for the field's `locale` (the device locale by default). `TimePickerField`, `TimeRangePickerField` and `DateTimePickerField` follow `format` (`'12h'`, `'24h'` or `'auto'`) and `showSeconds`.

For your own wording, pass `displayValue`:

```tsx
<DatePickerField
  label="Delivery"
  value={day}
  onConfirm={setDay}
  displayValue={day ? formatDate(day, undefined, { weekday: 'long', day: 'numeric', month: 'long' }) : undefined}
/>
```

When `displayValue` is empty and there's no value, the field shows `placeholder` (default `'Select…'`). In the Material design, a field with a `label` shows the label there instead, and the placeholder only while it's open.

## Label and sheet title

`label` is drawn above the field (in the Material design, inside it until there's a value, then on its top border), used as its accessibility label and, unless you set `title`, as the sheet's title (a bottom sheet or modal; the dropdown has no title).

```tsx
<TimePickerField label="Alarm" title="Wake me up at" value={alarm} onConfirm={setAlarm} />
```

## Clearing

`clearable` shows a × button while the field has a value. Reset your state in `onClear`:

```tsx
<DatePickerField label="Due" value={due} onConfirm={setDue} clearable onClear={() => setDue(null)} />
```

## Errors and helper text

`error` shows the field as invalid: a red border and label, and the message under the field when it's a string. `helperText` is the line under the field while there's no error message. `required` adds an asterisk to the label. The field doesn't check the value itself: your form decides what's invalid and when to say so, so set `error` from [React Hook Form, Formik or Zod](../guides/forms).

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { DatePickerField, Select } from 'patine-ui';
import { DemoButton } from './DemoButton';

const rooms = ['Standard', 'Deluxe', 'Suite'].map((r) => ({ label: r, value: r }));

export default function Example() {
  const [day, setDay] = useState<Date | null>(null);
  const [room, setRoom] = useState<string | null>(null);
  const [submitted, setSubmitted] = useState(false);
  return (
    <View style={{ gap: 14 }}>
      <DatePickerField
        label="Check-in"
        required
        helperText="You can change it until the day before"
        error={submitted && !day && 'Choose a check-in date'}
        value={day}
        onConfirm={setDay}
        minDate={new Date()}
      />
      <Select
        label="Room"
        required
        error={submitted && !room && 'Choose a room'}
        options={rooms}
        value={room}
        onValueChange={setRoom}
      />
      <DemoButton title="Book" onPress={() => setSubmitted(true)} />
    </View>
  );
}
```

`error={true}` marks the field without a message, and shows `helperText` in red. [`Select`](./select#errors-and-helper-text), [`CountryPicker`](./country-picker), [`TimeZonePicker`](./time-zone-picker) and [`PhoneField`](./phone-field#errors-and-helper-text) take the same three props.

## Custom trigger

`renderTrigger` replaces the field box, and gets `{ open, displayValue, disabled, error }`. The label sits above it, in Material too, the line under the field still shows, and the sheet still opens from the field. Use `error` to show your trigger as invalid.

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { EmojiPickerField } from 'patine-ui';

export default function Example() {
  const [icon, setIcon] = useState('🌱');
  return (
    <EmojiPickerField
      label="Project icon"
      value={icon}
      onSelect={setIcon}
      renderTrigger={({ open, displayValue }) => (
        <Pressable
          onPress={open}
          accessibilityRole="button"
          accessibilityLabel="Change project icon"
          style={{
            width: 64,
            height: 64,
            borderRadius: 16,
            alignItems: 'center',
            justifyContent: 'center',
            backgroundColor: '#F4F2EE',
          }}
        >
          <Text style={{ fontSize: 34 }}>{displayValue}</Text>
        </Pressable>
      )}
    />
  );
}
```

`renderChevron` swaps only the chevron icon and keeps its rotation, as in [Select](./select#custom-chevron).

## Your own sheet: `PickerField`

`PickerField` is the field without a picker. Its child is a function that gets `{ open, onOpenChange }` for the sheet you render (spread it on the sheet), so any [`BottomSheet`](./bottom-sheet) or [`PickerSheet`](./picker-sheets#pickersheet) can open from a field. A `PickerSheet` inside follows the field's `presentation`, so it opens as a dropdown on the web; a `presentation` set on the `PickerSheet` itself wins.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import {
  PickerField,
  PickerSheet,
  Switch,
  useDraft,
} from 'patine-ui';

type Prefs = { push: boolean; email: boolean };

const NotificationsSheet = ({
  open,
  onOpenChange,
  prefs,
  onSave,
}: {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  prefs: Prefs;
  onSave: (p: Prefs) => void;
}) => {
  const [draft, setDraft] = useDraft(prefs, open);
  return (
    <PickerSheet
      open={open}
      onOpenChange={onOpenChange}
      title="Notifications"
      confirmLabel="Save"
      onConfirm={() => {
        onSave(draft);
        onOpenChange(false);
      }}
    >
      <View style={{ padding: 16, gap: 16 }}>
        {(['push', 'email'] as const).map((k) => (
          <Switch
            key={k}
            label={k === 'push' ? 'Push' : 'Email'}
            checked={draft[k]}
            onCheckedChange={(v) => setDraft({ ...draft, [k]: v })}
          />
        ))}
      </View>
    </PickerSheet>
  );
};

export default function Example() {
  const [prefs, setPrefs] = useState<Prefs>({ push: true, email: false });
  const summary =
    [prefs.push && 'Push', prefs.email && 'Email']
      .filter(Boolean)
      .join(' + ') || 'Off';
  return (
    <PickerField label="Notifications" displayValue={summary}>
      {(sheet) => (
        <NotificationsSheet {...sheet} prefs={prefs} onSave={setPrefs} />
      )}
    </PickerField>
  );
}
```

## Styling

`style` styles the wrapper (label and field). `styles` takes the field's slots and the slots of the picker inside the sheet, so one object styles both:

```tsx
<DatePickerField
  label="Check-in"
  value={day}
  onConfirm={setDay}
  styles={{
    trigger: { borderRadius: 999 },
    triggerText: { fontWeight: '600' },
    selectedDay: { borderRadius: 8 },
  }}
/>
```

| Slot | Element |
| --- | --- |
| `label` | The label: above the field, or the floating label in the Material design |
| `trigger` | The field box |
| `triggerText` | The value |
| `placeholder` | Placeholder text |
| `chevron` | The drawn chevron (a bordered `View`: `borderColor` sets its color, `width` / `height` its size); in the Material design, a triangle colored by `borderTopColor` |
| `clear` | × button text |
| `helperText` | The line under the field: helper text or the error message |

The theme (`theme` prop or [`PatineProvider`](../guides/theming)) applies to the field and the sheet.

## Accessibility

The field is a button labelled with `label` (or the placeholder), with the current value as its hint and an `expanded` state while the picker is open. With `required`, the label ends in `, required`; with `error`, the message follows the value in the hint (`Invalid` for `error={true}`), and the line under the field is a live region, so screen readers announce an error as it appears. The dropdown closes on a tap outside it and on the Android back button. The × button is labelled `Clear`.

## Props

Every field takes these, plus its sheet's props without `open` / `onOpenChange` (the field owns them): `value`, `onConfirm` (`onSelect` for emoji), `title`, `confirmLabel`, `sheetProps`, the picker's own props (`mode`, `minDate`, `locale`, `items`, `minuteInterval`…). The picker's own `style` and `testID` aren't available on a field; `style` and `testID` belong to the field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Label above the field (floating inside it in Material). Also its accessibility label, and the sheet title unless `title` is set. |
| `placeholder` | `string` | `'Select…'` | Shown while there's no value. |
| `displayValue` | `string` | the value, formatted for `locale` | Text shown in the field. |
| `disabled` | `boolean` | `false` | The field doesn't open. |
| `clearable` | `boolean` | `false` | Show a × button while there's a value. |
| `onClear` | `() => void` | — | Called by ×. Reset your value here. |
| `error` | `string \| boolean` | — | Shows the field as invalid, with the message under it when it's a string. See [Errors and helper text](#errors-and-helper-text). |
| `helperText` | `string` | — | Shown under the field, replaced by the `error` message. |
| `required` | `boolean` | `false` | Adds an asterisk to the label and tells screen readers the field is required. The value isn't checked. |
| `renderTrigger` | `(info: { open, displayValue, disabled, error }) => ReactNode` | — | Replace the field box. |
| `renderChevron` | `(info: { open, theme }) => ReactNode` | — | Custom chevron icon. It still rotates on open and close. |
| `presentation` | `'auto' \| 'dropdown' \| 'bottomSheet' \| 'modal' \| 'inline'` | `'auto'` | Where the picker opens: a dropdown on the web, a bottom sheet on native. See [Dropdown, bottom sheet, modal or inline](#dropdown-bottom-sheet-modal-or-inline). |
| `open` | `boolean` | — | Open, when you control it. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` | `false` | Open at first, when the field keeps its own state. |
| `onOpenChange` | `(open: boolean) => void` | — | The user opened or closed the picker (Done, Cancel or dismiss). Not called when `open` changes from your code. |
| `style` | `StyleProp<ViewStyle>` | — | Wrapper style (label + field). |
| `styles` | `SlotStyles<PickerFieldSlot \| …>` | — | Field slots plus the picker's slots. |
| `theme` | `DeepPartial<Theme>` | — | Theme for the field and the sheet. |
| `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. Passed on to the sheet it opens. |
| `testID` | `string` | — | Test ID on the field box. |

`EmojiPickerField` also takes `value?: string`, the emoji to show. `PickerField` takes the props above (no sheet props), `children: (sheet: { open, onOpenChange }) => ReactNode`, and `icon`, a node shown before the value such as a colour swatch or a flag.

### Types

```ts
import type {
  DatePickerFieldProps,
  TimePickerFieldProps,
  TimeRangePickerFieldProps,
  DateTimePickerFieldProps,
  DurationPickerFieldProps,
  MonthPickerFieldProps,
  ColorPickerFieldProps,
  WheelPickerFieldProps,
  EmojiPickerFieldProps,
  PickerFieldProps,
  PickerFieldBaseProps,
  PickerFieldSlot,
  PickerFieldTriggerInfo,
  FieldPresentation,
  FieldStatusProps,
  FieldError,
  WithPickerField,
} from 'patine-ui';
```

`WithPickerField<SheetProps, Slot>` turns a sheet's props into a field's, for wrapping your own sheet the same way. `FieldStatusProps` is `{ error, helperText, required }`, for your own fields.

## Related

- [Picker sheets](./picker-sheets): the sheets on their own, when you control `open`
- [Select](./select): the select field these match
- [Forms](../guides/forms): React Hook Form and Formik
