# React Native Pickers

> @elik56a/react-native-pickers: pure-JS wheel, time, date (calendar, range, multiple, wheel), select and emoji pickers plus bottom sheets for React Native, Expo and React Native Web.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Introduction

## React Native Pickers

**One dependency-free package for every picker a React Native app needs** — wheel, time, date (calendar, range, multiple, wheel), select / dropdown, emoji, the bottom sheets to put them in, and the form fields that open them.

**npm**

```bash
npm install @elik56a/react-native-pickers
```

**yarn**

```bash
yarn add @elik56a/react-native-pickers
```

**pnpm**

```bash
pnpm add @elik56a/react-native-pickers
```

**Expo**

```bash
npx expo install @elik56a/react-native-pickers
```

It is **100% JavaScript with zero native code**, so it runs unchanged in **Expo Go**, **bare React Native** and **React Native Web**. There's no `pod install`, no rebuild and no config plugin.

```tsx live
import { useState } from 'react';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return <DatePicker value={date} onChange={setDate} minDate={new Date()} />;
}
```

:::tip Every example on this site is live
Edit the code and the result updates instantly. Each example is a complete file you can copy into your app as-is, imports included.
:::

### What's included

| Component | What it is |
| --- | --- |
| [`WheelPicker`](./components/wheel-picker) | iOS-style 3D wheel with infinite loop, disabled items, tap-to-type, custom rows |
| [`MultiWheelPicker`](./components/multi-wheel-picker) | Several wheels sharing one selection band (durations, units, anything multi-column) |
| [`TimePicker`](./components/time-picker) | 12h / 24h (auto from locale), minute & second steps, min / max time |
| [`DatePicker`](./components/date-picker) | Calendar with **single**, **range** and **multiple** selection, or a day/month/year **wheel** |
| [`DateTimePicker`](./components/date-time-picker) | Day and time together: an iOS-style wheel row, or a calendar with time wheels |
| [`SelectPicker`](./components/select-picker) | Form field that opens a searchable sheet; single or multi-select with chips, groups, icons |
| [`SelectList`](./components/select-list) | The same list, inline |
| [`EmojiPicker`](./components/emoji-picker) | 1,906 emojis, categories, search, skin tones, recents, version filtering |
| [`BottomSheet`](./components/bottom-sheet) | Animated sheet with drag-to-dismiss, for your own content |
| [`DatePickerSheet`, `TimePickerSheet`, `DateTimePickerSheet`, `WheelPickerSheet`, `EmojiPickerSheet`](./components/picker-sheets) | Ready-made pickers in a sheet with Cancel / Done and draft state |
| [`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField`, `EmojiPickerField`, `PickerField`](./components/picker-fields) | Form fields that open a picker sheet and show the picked value, styled like `SelectPicker` |

### Why this library

- **No native code.** Works in Expo Go and on the web with nothing to link. The UI and behaviour are identical on iOS, Android and web, so your design isn't at the mercy of each OS's picker.
- **One consistent API.** Every picker takes `value` + `onChange` (controlled) or `defaultValue` (uncontrolled), a `theme`, a `styles` object for each visual part, and render props for full control.
- **Themeable to the pixel.** Light and dark themes are built in and follow the OS automatically. Override any token globally with `PickersProvider`, or per component.
- **International.** Month, weekday and AM/PM names, the 12/24-hour clock, the first day of the week and the date-wheel order all come from `Intl` for any locale. Layouts flip for RTL.
- **Accessible.** Wheels are `adjustable` (VoiceOver / TalkBack swipe up and down). Days announce their full date, and selected / disabled states are exposed.
- **Fast.** Animations use the native driver. Wheels and the emoji grid are virtualized with fixed row layouts, and rows are memoized.
- **Typed.** Written in TypeScript, with generics for value types and discriminated unions for selection modes, so `mode="range"` gives you a typed `{ start, end }`.

### Requirements

| | Version |
| --- | --- |
| `react` | `>= 18` |
| `react-native` | `>= 0.72` |
| Expo | Any SDK (works in Expo Go) |
| `react-native-web` | Supported |

No other peer dependencies: no Reanimated, no Gesture Handler, no SVG.

### Where to next

- [Installation](./getting-started/installation): install and optional setup
- [Quick start](./getting-started/quick-start): every picker in five minutes
- [Core concepts](./getting-started/core-concepts): controlled vs uncontrolled, sheets and drafts, theming, slots
- [API reference](./api/reference): every export in one page

---

## For AI assistants

This documentation is published in machine-readable form, following the [llms.txt](https://llmstxt.org) convention:

| File | Contents |
| --- | --- |
| [`/llms.txt`](pathname:///llms.txt) | Index of every page with a one-line summary |
| [`/llms-full.txt`](pathname:///llms-full.txt) | **The entire documentation in one Markdown file**: every component, prop table and example |
| `/docs/**/*.md` | Each page as plain Markdown |

Paste `llms-full.txt` into your assistant's context, or point Cursor / Claude / Copilot at the URL.

`llms-full.txt` also ships inside the npm package, so a coding agent can read it offline from `node_modules/@elik56a/react-native-pickers/llms-full.txt`, always matching the installed version.

### Cheat sheet

```text
Package: @elik56a/react-native-pickers   (npm i @elik56a/react-native-pickers)
Pure JS, zero native code, no peer deps besides react >=18 and react-native >=0.72.
Works in Expo Go, bare RN, React Native Web. All exports are named exports from the package root.
Native apps: prefer subpaths so Metro skips unused pickers (root import bundles ~130 KB of emoji data):
  /wheel /time /date /calendar /datetime /select /emoji /sheet /core   e.g. '@elik56a/react-native-pickers/date'
  PickersProvider and theme/date utils live in /core. Subpaths need RN 0.79+ (Metro package exports).

Controlled: value + onChange. Uncontrolled: defaultValue. SelectPicker/SelectList are controlled-only.
onChange fires on user changes only (not when value is set programmatically). Wheels fire onChange when they settle;
onValueChanging fires on every row crossing (use for haptics).

WheelPicker<T>     items: (T | {label, value, disabled?})[]  value  onChange(value, index)  loop  itemHeight=40  visibleItems=5
                   variant '3d'|'flat'  keyboardInput=true  isEqual  renderItem({item,index,selected,theme})  styles
MultiWheelPicker   columns: [{ key, items, value, onChange, flex?, width?, loop? }]  separator: node | (leftIndex)=>node
TimePicker         value: Date  onChange(date)  format '12h'|'24h'|'auto'  minuteInterval  showSeconds  minTime/maxTime  locale
DatePicker         display 'calendar'(default)|'wheel'
  mode 'single'    value: Date|null       onChange(date)
  mode 'range'     value: {start,end}     onChange(range)   minRangeDays maxRangeDays allowSingleDayRange
  mode 'multiple'  value: Date[]          onChange(dates)   maxSelections
  mode 'ranges'    value: DateRange[]     onChange(ranges)  maxRanges minRangeDays maxRangeDays allowSingleDayRange
  minDate maxDate isDateDisabled(date) markedDates{'YYYY-MM-DD':{dots?,label?,textColor?,disabled?}}
  locale firstDayOfWeek(0=Sun) initialMonth onMonthChange renderDay(state,theme) dayHeight=44
DateWheelPicker    value: Date  onChange  order ['day','month','year']  monthFormat 'long'|'short'|'numeric'  min/maxDate
SelectPicker<T>    options: {label,value,description?,icon?,group?,disabled?,keywords?}[]  value  onChange(value, option)
                   multiple → value T[], onChange(values, options), maxSelected, chips
                   label placeholder searchable(dropdown: type in field, default on; sheet: >8 auto) clearable+onClear (single: reset value in onClear) renderTrigger({open,selected}) renderChevron({open,theme})
SelectList<T>      same list inline: options value onChange multiple listHeight
EmojiPicker        onSelect(emoji, data) columns=8 height=380 categories exclude maxEmojiVersion skinTone recent onRecentChange
BottomSheet        visible onClose title headerLeft headerRight footer height(<=1 fraction | px) enableSwipeToClose draggable(header drags too; native:true web:false; handle always drags) expandable expandedHeight
Sheets (draft; commit on Done):
  DatePickerSheet  visible onClose value onConfirm + all calendar props + mode + display + confirmOnSelect
  TimePickerSheet  visible onClose value onConfirm + TimePicker props
  WheelPickerSheet visible onClose items value onConfirm
  EmojiPickerSheet visible onClose onSelect closeOnSelect=true
  DateTimePickerSheet visible onClose value onConfirm + DateTimePicker props
  PickerSheet      visible onClose onConfirm children  +  useDraft(value, visible)
Fields (a SelectPicker-style field that opens the sheet and shows the confirmed value; field owns open state):
  DatePickerField / TimePickerField / DateTimePickerField / WheelPickerField / EmojiPickerField
                   = the matching *Sheet props WITHOUT visible (value, onConfirm | onSelect, mode, locale, title...)
                   + label placeholder='Select…' displayValue(default: value formatted for locale) clearable+onClear(reset value there)
                     disabled renderTrigger({open,displayValue,disabled}) renderChevron({open,theme}) onOpen onClose style testID
                   styles = field slots (label trigger triggerText placeholder chevron clear) + the picker's slots
                   EmojiPickerField also takes value: string (the emoji shown). Sheet title defaults to label.
  PickerField      same field props, children: ({visible, onClose}) => <AnySheet .../>
Theme: <PickersProvider colorScheme='auto'|'light'|'dark' theme={...} darkTheme={...}>; per-component `theme` prop.
  tokens: colors{background,surface,sheet,text,textSecondary,textDisabled,primary,onPrimary,primaryMuted,border,backdrop,indicator,handle}
          radius{sm,md,lg,full,sheet} spacing{xs..xl} typography{fontFamily,fontFamilyMedium,sizes,weights} animation{duration}
Slots: every component takes `styles={{ slotName: style }}`.
Utils: toDateKey(d) 'YYYY-MM-DD' local; addDays addMonths isSameDay compareDay isBetweenDays formatDate(d, locale, opts)
       searchEmojis findEmoji withSkinTone getAllEmojis; defaultFilter for select search.
```

### Canonical examples

```tsx
import { useState } from 'react';
import { DatePicker, DatePickerField, DatePickerSheet, SelectPicker, TimePicker, TimePickerField, WheelPicker } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

function Examples() {
  const [size, setSize] = useState('M');
  const [time, setTime] = useState(new Date());
  const [date, setDate] = useState<Date | null>(null);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  const [country, setCountry] = useState<string | null>(null);
  const [open, setOpen] = useState(false);

  return (
    <>
      <WheelPicker items={['S', 'M', 'L']} value={size} onChange={setSize} />
      <TimePicker value={time} onChange={setTime} minuteInterval={5} />
      <DatePicker value={date} onChange={setDate} minDate={new Date()} />
      <DatePicker mode="range" value={range} onChange={setRange} />
      <SelectPicker label="Country" options={[{ label: 'Israel', value: 'IL' }]} value={country} onChange={setCountry} />
      <DatePickerSheet visible={open} onClose={() => setOpen(false)} mode="range" value={range} onConfirm={setRange} />
      {/* In forms: a field that opens the sheet and shows the value, no open state needed */}
      <DatePickerField label="Stay" mode="range" value={range} onConfirm={setRange} placeholder="Add dates" />
      <TimePickerField label="Time" value={time} onConfirm={setTime} />
    </>
  );
}
```

---

## Install React Native Pickers

## Installation

React Native Pickers is pure JavaScript: one package, with no native linking, pods or rebuilds.

**npm**

```bash
npm install @elik56a/react-native-pickers
```

**yarn**

```bash
yarn add @elik56a/react-native-pickers
```

**pnpm**

```bash
pnpm add @elik56a/react-native-pickers
```

**Expo**

```bash
npx expo install @elik56a/react-native-pickers
```

That's it. The package is pure JavaScript, so there is:

- no `pod install`
- no native rebuild — it works in **Expo Go**
- no Babel plugin, Metro config or config plugin
- no other dependency (no Reanimated, Gesture Handler or SVG)

Peer dependencies are `react >= 18` and `react-native >= 0.72`, which your app already has.

### Optional: add the theme provider

Every component works with sensible light and dark defaults that follow the OS appearance. To use your brand colours everywhere, wrap your app once:

```tsx title="App.tsx"
import { PickersProvider } from '@elik56a/react-native-pickers';

export default function App() {
  return (
    <PickersProvider theme={{ colors: { primary: '#FF5A5F' } }}>
      <RootNavigator />
    </PickersProvider>
  );
}
```

See [Theming](../guides/theming) for every token.

### React Native Web

Nothing extra is needed beyond a standard `react-native-web` setup (Expo web already has one). If you bundle manually, alias `react-native` to `react-native-web`:

```js title="webpack.config.js"
module.exports = {
  resolve: { alias: { 'react-native$': 'react-native-web' } },
};
```

This documentation site is itself built this way: every live example is the real library running on React Native Web.

### Importing

Everything is a named export from the package root:

```tsx
import {
  WheelPicker,
  MultiWheelPicker,
  TimePicker,
  DatePicker,
  Calendar,
  DateWheelPicker,
  SelectPicker,
  SelectList,
  EmojiPicker,
  BottomSheet,
  PickerSheet,
  DatePickerSheet,
  TimePickerSheet,
  WheelPickerSheet,
  EmojiPickerSheet,
  PickersProvider,
} from '@elik56a/react-native-pickers';
```

The package is marked `sideEffects: false`, so bundlers that tree-shake (web) drop what you don't import. On native, Metro resolves the TypeScript source through the `react-native` export condition.

#### Smaller native bundles

Metro doesn't tree-shake, so a root import bundles every picker on iOS and Android, including about 130 KB of emoji data. Import from the feature subpaths instead and Metro only bundles what you use:

```tsx
import { DatePicker, DatePickerSheet } from '@elik56a/react-native-pickers/date';
import { SelectPicker } from '@elik56a/react-native-pickers/select';
import { PickersProvider } from '@elik56a/react-native-pickers/core';
```

| Subpath | Exports |
| --- | --- |
| `/wheel` | `WheelPicker`, `MultiWheelPicker`, `WheelPickerSheet` |
| `/time` | `TimePicker`, `TimePickerSheet` |
| `/date` | `DatePicker`, `DateWheelPicker`, `DatePickerSheet` |
| `/calendar` | `Calendar` |
| `/datetime` | `DateTimePicker`, `DateTimePickerSheet` |
| `/select` | `SelectPicker`, `SelectList` |
| `/emoji` | `EmojiPicker`, `EmojiPickerSheet`, emoji utils |
| `/sheet` | `BottomSheet`, `PickerSheet`, `useDraft` |
| `/core` | `PickersProvider`, themes, date utils |

Each subpath also exports its types. Subpaths need React Native 0.79+ (Expo SDK 53+), where Metro reads package `exports` by default. On older versions, set `resolver.unstable_enablePackageExports = true` in `metro.config.js` or keep the root import.

---

## Quick start

Each block below is a complete, runnable component. Edit it, and copy it straight into your app when you're done.

### Wheel

Pass primitives or `{ label, value }` objects.

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [size, setSize] = useState('M');
  return <WheelPicker items={['XS', 'S', 'M', 'L', 'XL', 'XXL']} value={size} onChange={setSize} />;
}
```

### Time

The 12h / 24h format comes from the locale automatically.

```tsx live
import { useState } from 'react';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [time, setTime] = useState(new Date());
  return <TimePicker value={time} onChange={setTime} minuteInterval={5} />;
}
```

### Date (calendar)

```tsx live
import { useState } from 'react';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(null);
  return <DatePicker value={date} onChange={setDate} minDate={new Date()} />;
}
```

### Date range

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return (
    <>
      <DatePicker mode="range" value={range} onChange={setRange} minDate={new Date()} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {range.start ? formatDate(range.start) : '—'} → {range.end ? formatDate(range.end) : '—'}
      </Text>
    </>
  );
}
```

### Date (wheel)

```tsx live
import { useState } from 'react';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [birthday, setBirthday] = useState(new Date(1990, 4, 17));
  return <DatePicker display="wheel" value={birthday} onChange={setBirthday} maxDate={new Date()} />;
}
```

### Select

Tap the field to open a searchable bottom sheet.

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

const languages = [
  { label: 'English', value: 'en' },
  { label: 'Español', value: 'es' },
  { label: 'Français', value: 'fr' },
  { label: 'Deutsch', value: 'de' },
  { label: 'עברית', value: 'he', keywords: ['hebrew'] },
];

export default function Example() {
  const [lang, setLang] = useState<string | null>(null);
  return <SelectPicker label="Language" placeholder="Choose a language" options={languages} value={lang} onChange={setLang} />;
}
```

### Emoji

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { EmojiPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [text, setText] = useState('');
  return (
    <>
      <Text style={{ fontSize: 28, minHeight: 40 }}>{text}</Text>
      <EmojiPicker height={320} onSelect={(emoji) => setText((t) => t + emoji)} />
    </>
  );
}
```

### In a bottom sheet

Every picker also ships as a sheet. The sheet keeps a **draft** and only calls `onConfirm` when the user taps **Done**; **Cancel**, a backdrop tap or a swipe down discards it.

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { DatePickerSheet, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const [open, setOpen] = useState(false);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ backgroundColor: '#C8460D', padding: 14, borderRadius: 12 }}>
        <Text style={{ color: 'white', fontWeight: '600', textAlign: 'center' }}>
          {range.start && range.end ? `${formatDate(range.start)} → ${formatDate(range.end)}` : 'Pick dates'}
        </Text>
      </Pressable>
      <DatePickerSheet
        visible={open}
        onClose={() => setOpen(false)}
        title="Check-in / Check-out"
        mode="range"
        value={range}
        onConfirm={setRange}
        minDate={new Date()}
      />
    </>
  );
}
```

### In a form field

A field opens the sheet for you and shows the confirmed value, so there's no open state to manage. Each sheet has one: `DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField` and `EmojiPickerField`.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { DatePickerField, TimePickerField } from '@elik56a/react-native-pickers';

export default function Example() {
  const [day, setDay] = useState<Date | null>(null);
  const [time, setTime] = useState<Date | undefined>();
  return (
    <View style={{ gap: 14 }}>
      <DatePickerField label="Date" placeholder="Pick a date" value={day} onConfirm={setDay} minDate={new Date()} />
      <TimePickerField label="Time" placeholder="Pick a time" value={time} onConfirm={setTime} minuteInterval={15} />
    </View>
  );
}
```

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

### Next

- [Core concepts](./core-concepts): the few ideas every component shares
- [Components](../components/wheel-picker): full props for each picker

---

## Core concepts

Every component follows the same handful of conventions. Learn them once and you know the whole library.

### Controlled and uncontrolled

Wheels, time, date and emoji state can be used either way:

```tsx
// Controlled: you own the state
const [date, setDate] = useState(new Date());
<TimePicker value={date} onChange={setDate} />

// Uncontrolled: the component owns it; you only listen
<TimePicker defaultValue={new Date()} onChange={(d) => console.log(d)} />
```

| Component | Controlled | Uncontrolled |
| --- | --- | --- |
| `WheelPicker` | `value` | `defaultValue` |
| `TimePicker` | `value` | `defaultValue` (default: now) |
| `DatePicker` / `Calendar` | `value` | `defaultValue` |
| `DateWheelPicker` | `value` | `defaultValue` (default: today) |
| `EmojiPicker` skin tone | `skinTone` | `defaultSkinTone` |
| `EmojiPicker` recents | `recent` | `defaultRecent` |
| `SelectPicker` / `SelectList` | `value` | — (always controlled) |

:::caution Select is controlled-only
`SelectPicker` and `SelectList` don't keep their own selection. Always pass `value` and update it in `onChange`.
:::

Setting `value` from outside (for example, a "Reset" button) moves the component **without** firing `onChange`. `onChange` only reports changes the user made.

### `onChange` vs `onValueChanging`

Wheel-based pickers (`WheelPicker`, `MultiWheelPicker` columns, `TimePicker`, `DateWheelPicker`) fire two callbacks:

| Callback | When | Use it for |
| --- | --- | --- |
| `onChange` | Once, after the wheel **settles** on a new value | Updating state, saving |
| `onValueChanging` | On **every row crossing** while scrolling | Haptics, live previews |

```tsx
<WheelPicker
  items={items}
  value={value}
  onChange={setValue}
  onValueChanging={() => Haptics.selectionAsync()}
/>
```

### Sheets and drafts

`DatePickerSheet`, `TimePickerSheet` and `WheelPickerSheet` wrap a picker in a [`BottomSheet`](../components/bottom-sheet) with **Cancel** and **Done**:

- The sheet copies `value` into a **draft** each time it opens.
- Scrolling or tapping changes only the draft.
- **Done** calls `onConfirm(draft)`, then `onClose()`.
- **Cancel**, a backdrop tap, a swipe down or Android back calls `onClose()` only, so the draft is discarded.

```tsx
<TimePickerSheet visible={open} onClose={() => setOpen(false)} value={time} onConfirm={setTime} />
```

`EmojiPickerSheet` has no Done button: picking an emoji calls `onSelect` and (by default) closes the sheet. `SelectPicker` opens its own sheet; you don't manage `visible`.

### Fields

In a form, the picker hides behind a field. `SelectPicker` is one, and every sheet has a field version that takes the same props without `visible` / `onClose`: [`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField`, `EmojiPickerField`](../components/picker-fields). The field owns the open state, shows the confirmed value formatted for `locale`, and looks the same as `SelectPicker`'s field.

```tsx
<TimePickerField label="Alarm" value={time} onConfirm={setTime} />
```

### Theming

Three layers, each merged on top of the previous one:

1. Built-in `lightTheme` / `darkTheme`, chosen from the OS appearance
2. `<PickersProvider theme={…} darkTheme={…}>` for your whole app
3. The `theme` prop on any single component

```tsx
<PickersProvider theme={{ colors: { primary: '#0EA5E9' }, radius: { md: 6 } }}>
  <DatePicker theme={{ colors: { primary: '#22C55E' } }} />  {/* green only here */}
</PickersProvider>
```

→ [Theming guide](../guides/theming)

### Slot styles

Every visual part of a component has a named **slot**. Pass styles for any of them through `styles`:

```tsx
<DatePicker
  styles={{
    selectedDay: { borderRadius: 8 },
    headerTitle: { fontSize: 20 },
    rangeBand: { backgroundColor: '#FFE4E6' },
  }}
/>
```

Slot names are typed, so your editor autocompletes them. Each component page lists its slots. → [Styling guide](../guides/styling)

### Render props

When styles aren't enough, replace a part entirely:

| Component | Render props |
| --- | --- |
| `WheelPicker` | `renderItem`, `renderIndicator` |
| `DatePicker` / `Calendar` | `renderDay`, `renderArrow`, `formatTitle` |
| `SelectPicker` / `SelectList` | `renderTrigger`, `renderOption`, `renderGroupHeader` |
| `EmojiPicker` | `renderEmoji`, `categoryIcons` |
| `*PickerField` / `PickerField` | `renderTrigger`, `renderChevron` |

→ [Render props guide](../guides/render-props)

### Strings and i18n

No component hard-codes a user-facing string you can't change. Done, Cancel, placeholders, search hints, empty states and category labels are all props. Month, weekday and AM/PM names come from `Intl` for whatever `locale` you pass. → [i18n & RTL](../guides/i18n-rtl)

---

## React Native Bottom Sheet

## BottomSheet

`BottomSheet` is the React Native bottom sheet every picker sheet is built on, exported so your own content can use it: filters, menus, confirmations, forms. It slides up over a dimmed backdrop, can be dragged down to dismiss, and is built on React Native's `Modal`, `Animated` and `PanResponder` only.

```tsx
import { BottomSheet } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { Pressable, Text, View } from 'react-native';
import { BottomSheet } from '@elik56a/react-native-pickers';

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ backgroundColor: '#C8460D', padding: 14, borderRadius: 12 }}>
        <Text style={{ color: 'white', fontWeight: '600', textAlign: 'center' }}>Open sheet</Text>
      </Pressable>
      <BottomSheet
        visible={open}
        onClose={() => setOpen(false)}
        title="Share"
        footer={
          <Pressable onPress={() => setOpen(false)} style={{ backgroundColor: '#F4F2EE', padding: 14, borderRadius: 12 }}>
            <Text style={{ textAlign: 'center', fontWeight: '600' }}>Close</Text>
          </Pressable>
        }
      >
        <View style={{ padding: 16, gap: 12 }}>
          {['Copy link', 'Send via message', 'Share to…'].map((a) => (
            <Text key={a} style={{ fontSize: 16 }}>{a}</Text>
          ))}
        </View>
      </BottomSheet>
    </>
  );
}
```

### Try the props

    {['Copy link', 'Send via message', 'Share to…'].map((a) => (
      {a}
    ))}

### Bottom sheet or modal

`presentation` switches between a bottom sheet and a centered modal:

- `'auto'` (default): a modal on web windows wider than the sheet (688 px), a bottom sheet everywhere else.
- `'bottomSheet'`: always slides up from the bottom, with a drag handle.
- `'modal'`: always a centered dialog that fades in, with no drag handle or swipe-to-close.

```tsx
<BottomSheet presentation="modal" visible={open} onClose={close} title="Confirm">
  …
</BottomSheet>
```

### Opening and closing

`BottomSheet` is fully controlled: render it with `visible` and change `visible` in `onClose`. `onClose` is called when the user:

- taps the backdrop (`closeOnBackdropPress`, default `true`)
- drags the sheet down past about 30% of its height (max 140 px), or flicks it down; on the web, scrolls the wheel down over it (`enableSwipeToClose`, default `true`)
- presses Android's back button

When `visible` turns `false`, the sheet animates out and then unmounts its children. `onOpened` and `onClosed` fire when the animations finish, which is handy for focusing inputs or running work after the sheet is gone.

### Header

The header row shows when you pass `title`, `headerLeft` or `headerRight`. A string `title` is styled for you (use the `title` slot); a node is rendered as-is. The drag handle and header are both drag areas.

```tsx
<BottomSheet
  visible={open}
  onClose={close}
  title="Filters"
  headerLeft={<Button title="Reset" onPress={reset} />}
  headerRight={<Button title="Apply" onPress={apply} />}
>
  …
</BottomSheet>
```

### Height

- **Default**: the sheet sizes to its content, up to `maxHeightRatio` (default `0.9`) of the window.
- **`height` ≤ 1**: a fraction of the window height (`height={0.6}` → 60%).
- **`height` > 1**: pixels.

With a fixed height, the content area becomes `flex: 1`, so a `FlatList` or `ScrollView` inside fills it and scrolls.

`bottomInset` adds bottom padding for the home indicator (default 24 on iOS, 12 elsewhere). Pass your safe-area inset for pixel-perfect results:

```tsx
const insets = useSafeAreaInsets();
<BottomSheet bottomInset={insets.bottom + 8} … />
```

On tablets and the web the sheet is centred with a maximum width of 640.

### Expanding to full screen

The sheet can grow past its content height to `expandedHeight` (default: the whole window below the status bar), and collapse back:

| | Expand | Collapse, then close |
| --- | --- | --- |
| **iOS / Android** | Drag the handle or header up | Drag it down |
| **Web** | Wheel up over the sheet, or drag the handle up | Wheel down, or drag the handle down |

Released past halfway, or with a flick, the sheet snaps to the expanded height; otherwise it settles back. A list or scroll view inside keeps the wheel until it reaches its top or bottom, then the sheet takes over.

The handle always drags. On the web the header row doesn't by default (`draggable={false}`), so mouse drags there still select text; pass `draggable` to make the whole header a drag area. `expandable={false}` keeps the sheet at its content height on every platform.

Try it: open the sheet, then scroll the wheel up over it (or drag the header, since this example turns `draggable` on). Wide web windows show a centered modal by default, so the examples here force `presentation="bottomSheet"`:

```tsx live
import { useState } from 'react';
import { Pressable, ScrollView, Text, View } from 'react-native';
import { BottomSheet } from '@elik56a/react-native-pickers';

const comments = Array.from({ length: 30 }, (_, i) => `Comment #${i + 1}: looks great!`);

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ backgroundColor: '#C8460D', padding: 14, borderRadius: 12 }}>
        <Text style={{ color: 'white', fontWeight: '600', textAlign: 'center' }}>Open comments</Text>
      </Pressable>
      <BottomSheet
        visible={open}
        onClose={() => setOpen(false)}
        title="Comments"
        presentation="bottomSheet"
        draggable
        height={0.45}
        expandedHeight={0.9}
      >
        <ScrollView contentContainerStyle={{ padding: 16, gap: 14 }}>
          {comments.map((c) => (
            <Text key={c} style={{ fontSize: 15 }}>{c}</Text>
          ))}
        </ScrollView>
      </BottomSheet>
    </>
  );
}
```

The list scrolls first; once it's back at the top, wheeling up expands the sheet, and wheeling down at the bottom collapses it, then closes it.

#### Configuring it

```tsx
// Expand to 85% of the window instead of full screen
<BottomSheet expandedHeight={0.85} … />

// Expand to a fixed height in px
<BottomSheet expandedHeight={600} … />

// Mouse dragging on the web too
<BottomSheet draggable … />

// No expanding: drag (or wheel) down still closes it
<BottomSheet expandable={false} … />

// Fixed at its height: no expanding, no swipe or wheel to close
<BottomSheet expandable={false} enableSwipeToClose={false} … />
```

Every picker sheet takes the same props through `sheetProps`:

```tsx
<DatePickerSheet visible={open} onClose={close} sheetProps={{ expandedHeight: 0.8 }} … />
```

### Keyboard

On iOS the sheet is wrapped in a `KeyboardAvoidingView`, so text inputs inside stay visible above the keyboard.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` | **required** | Show or hide (animated). |
| `onClose` | `() => void` | **required** | Requested close: backdrop, swipe, Android back. |
| `children` | `ReactNode` | **required** | Sheet content. |
| `title` | `ReactNode` | — | Header title; strings get the title style. |
| `headerLeft` | `ReactNode` | — | Left side of the header. |
| `headerRight` | `ReactNode` | — | Right side of the header. |
| `footer` | `ReactNode` | — | Content pinned below the children. |
| `presentation` | `'auto' \| 'bottomSheet' \| 'modal'` | `'auto'` | Bottom sheet or centered modal; `auto` is a modal on wide web windows. |
| `enableSwipeToClose` | `boolean` | `true` | Drag down (wheel down on the web) to dismiss (bottom sheet only). |
| `draggable` | `boolean` | `true` native / `false` web | The header row drags too, not just the handle. |
| `expandable` | `boolean` | `true` | Grow to `expandedHeight`: drag up on native, wheel up on the web. |
| `expandedHeight` | `number` | window − status bar | Expanded height: fraction (≤ 1) or px. |
| `closeOnBackdropPress` | `boolean` | `true` | Tap outside to dismiss. |
| `maxHeightRatio` | `number` | `0.9` | Max height as a fraction of the window. |
| `height` | `number` | content | Fixed height: fraction (≤ 1) or px. |
| `bottomInset` | `number` | `24` iOS / `12` | Bottom padding. |
| `onOpened` | `() => void` | — | Open animation finished. |
| `onClosed` | `() => void` | — | Close animation finished (content unmounted). |
| `styles` | `SlotStyles<BottomSheetSlot>` | — | Slots below. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override (`sheet`, `backdrop`, `handle`, `radius.sheet`…). |
| `testID` | `string` | — | Test ID on the modal. |

#### Slots

| Slot | Element |
| --- | --- |
| `backdrop` | Dimmed overlay |
| `sheet` | The sheet surface |
| `handle` | Grab handle |
| `header` | Header row |
| `title` | String title text |
| `content` | Children wrapper |
| `footer` | Footer wrapper |

#### Theme tokens used

`colors.sheet` (background), `colors.backdrop`, `colors.handle`, `radius.sheet` (top corners), `animation.duration`.

### Related

- [PickerSheet](./picker-sheets#pickersheet): a BottomSheet with Cancel / Done buttons
- [Filters sheet recipe](../recipes/filters-sheet)

---

## React Native Date Picker & Calendar

## DatePicker & Calendar

`DatePicker` is a React Native date picker that shows a month calendar. It supports **single**, **range** and **multiple** selection, min / max dates, disabled days, dots and labels under days, swipe navigation, a quick month jump and any locale.

```tsx
import { DatePicker, Calendar } from '@elik56a/react-native-pickers';
```

- **`DatePicker`** is the entry point. With `display="calendar"` (the default) it renders a `Calendar`, and with `display="wheel"` it renders a [`DateWheelPicker`](./date-wheel-picker).
- **`Calendar`** is what `DatePicker` renders by default, with the same props minus `display`. `<DatePicker />` and `<Calendar />` look and behave the same; import `Calendar` directly if you never need the wheel.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker, formatDate } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(null);
  return (
    <>
      <DatePicker value={date} onChange={setDate} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>{date ? formatDate(date, undefined, { dateStyle: 'full' }) : 'No date selected'}</Text>
    </>
  );
}
```

This page covers single selection and everything the calendar shares. **Range** and **multiple** selection are on the [Date range & multiple](./date-range-picker) page.

### Try the props

### Min and max dates

Days outside `[minDate, maxDate]` are disabled (struck through). The arrows stop at the first and last allowed months, and the month grid greys out months outside the range. Only the **day** matters; the time of day is ignored.

```tsx live
import { useState } from 'react';
import { DatePicker, addDays } from '@elik56a/react-native-pickers';

export default function Example() {
  const today = new Date();
  const [date, setDate] = useState<Date | null>(addDays(today, 2));
  return <DatePicker value={date} onChange={setDate} minDate={today} maxDate={addDays(today, 45)} />;
}
```

### Disabling days

`isDateDisabled` runs for every visible day. Return `true` to disable it.

```tsx live
import { useState } from 'react';
import { DatePicker, toDateKey } from '@elik56a/react-native-pickers';

const holidays = new Set(['2026-12-25', '2026-12-26', '2027-01-01']);

export default function Example() {
  const [date, setDate] = useState<Date | null>(null);
  return (
    <DatePicker
      value={date}
      onChange={setDate}
      initialMonth={new Date(2026, 11, 1)}
      isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6 || holidays.has(toDateKey(d))}
    />
  );
}
```

You can also disable specific days through `markedDates` with `disabled: true`.

:::tip Keep it cheap
`isDateDisabled` is called up to 42 times per render. Avoid heavy work inside it; precompute a `Set` of disabled keys and check it with [`toDateKey`](../api/date-utils#todatekey).
:::

### Marked dates: dots, labels and colours

`markedDates` is keyed by `YYYY-MM-DD` (local time; build keys with [`toDateKey`](../api/date-utils#todatekey)). Each entry can have:

| Field | Type | Effect |
| --- | --- | --- |
| `dots` | `string[]` | Up to 3 coloured dots under the number (events, statuses) |
| `label` | `string` | Small text under the number (prices, counts) |
| `textColor` | `string` | Colour of the day number |
| `disabled` | `boolean` | Disable the day |

```tsx live
import { useState } from 'react';
import { DatePicker, toDateKey, addDays } from '@elik56a/react-native-pickers';

export default function Example() {
  const today = new Date();
  const [date, setDate] = useState<Date | null>(null);
  const marks = {
    [toDateKey(addDays(today, 1))]: { dots: ['#22C55E'] },
    [toDateKey(addDays(today, 3))]: { dots: ['#22C55E', '#F59E0B', '#EF4444'] },
    [toDateKey(addDays(today, 5))]: { label: '$89' },
    [toDateKey(addDays(today, 6))]: { label: '$129', textColor: '#EF4444' },
    [toDateKey(addDays(today, 8))]: { disabled: true, label: 'Full' },
  };
  return <DatePicker value={date} onChange={setDate} markedDates={marks} />;
}
```

### Locale and first day of week

Month and weekday names come from `Intl.DateTimeFormat` for the `locale` you pass. `firstDayOfWeek` (0 = Sunday … 6 = Saturday) defaults to the locale's first day when `Intl.Locale` week info is available, else Sunday.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <View style={{ gap: 24 }}>
      <DatePicker value={date} onChange={setDate} locale="fr-FR" firstDayOfWeek={1} />
      <DatePicker value={date} onChange={setDate} locale="ja-JP" weekdayFormat="narrow" />
    </View>
  );
}
```

### Navigation

- **Arrows** step one month. They're disabled at `minDate` / `maxDate`.
- **Swipe** left / right on the days to change month (`enableSwipe`, on by default). The direction flips in RTL.
- **Quick jump**: tap the month title to open a grid of months (the arrows step by year), tap the title again for a grid of years (the arrows step by 12 years), and tap it once more to go back to days. Picking a year opens its months, and picking a month opens its days (`enableQuickJump`, on by default). The year grid is limited to `yearRange`, which defaults to the `minDate` / `maxDate` years or 100 years either side of today.
- `initialMonth` sets the first month shown. By default it's the month of the selected date (or range start, or first multiple date), else today.
- `onMonthChange(month)` fires with the first day of the newly shown month.

In single mode, when `value` changes from outside to a date in another month, the calendar follows it.

### Layout

```tsx live
import { useState } from 'react';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <DatePicker
      value={date}
      onChange={setDate}
      showOutsideDays={false}
      fixedWeeks={false}
      dayHeight={38}
      formatTitle={(month) => month.toLocaleDateString('en-US', { month: 'short', year: '2-digit' })}
    />
  );
}
```

- `fixedWeeks` (default `true`) always renders 6 rows so the height never jumps between months. Set it to `false` to render only the weeks the month needs.
- `showOutsideDays` (default `true`) shows the trailing and leading days of neighbouring months (tappable, dimmed).
- `dayHeight` (default `44`) is the row height; the selection circle is `min(dayHeight − 4, 40)`.
- `showWeekdays={false}` hides the weekday header row.

### Custom days and arrows

`renderDay(state, theme)` fully replaces a day cell's content (taps and the range band are still handled for you). `renderArrow(direction, disabled)` replaces the arrows.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <DatePicker
      value={date}
      onChange={setDate}
      renderArrow={(dir, disabled) => <Text style={{ fontSize: 16, opacity: disabled ? 0.3 : 1 }}>{dir === 'prev' ? '⬅️' : '➡️'}</Text>}
      renderDay={(s, theme) => (
        <View
          style={{
            width: 36,
            height: 36,
            borderRadius: 10,
            alignItems: 'center',
            justifyContent: 'center',
            backgroundColor: s.selected ? theme.colors.primary : s.today ? theme.colors.primaryMuted : 'transparent',
            opacity: s.outside ? 0.35 : 1,
          }}
        >
          <Text style={{ color: s.selected ? theme.colors.onPrimary : s.disabled ? theme.colors.textDisabled : theme.colors.text, fontWeight: '600' }}>
            {s.date.getDate()}
          </Text>
        </View>
      )}
    />
  );
}
```

`DayState` passed to `renderDay`:

```ts
interface DayState {
  date: Date;
  selected: boolean;   // the selected day, a range end, or one of multiple
  rangeStart: boolean;
  rangeEnd: boolean;
  inRange: boolean;    // strictly between start and end
  today: boolean;
  disabled: boolean;
  outside: boolean;    // belongs to the previous / next month
  marking?: MarkedDate;
}
```

### Styling

```tsx live
import { useState } from 'react';
import { DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <DatePicker
      value={date}
      onChange={setDate}
      theme={{ colors: { primary: '#059669', primaryMuted: 'rgba(5,150,105,0.12)' } }}
      styles={{
        container: { borderRadius: 20, borderWidth: 1, borderColor: '#E8E4DC', paddingHorizontal: 8 },
        headerTitle: { fontSize: 20, fontWeight: '800' },
        weekdayText: { textTransform: 'uppercase', fontSize: 10, letterSpacing: 1 },
        selectedDay: { borderRadius: 10 },
        todayDay: { borderRadius: 10 },
      }}
    />
  );
}
```

#### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `header` | Title + arrows row |
| `headerTitle` | Month / year title text |
| `arrow` | Arrow button |
| `arrowText` | Default arrow glyph |
| `weekdays` | Weekday header row |
| `weekdayText` | Weekday labels |
| `week` | Each week row |
| `day` | Day cell (pressable, full width of the column) |
| `dayInner` | The circle inside the cell |
| `dayText` | Day number |
| `selectedDay` / `selectedDayText` | Selected circle / number |
| `todayDay` / `todayDayText` | Today's circle / number |
| `disabledDayText` | Disabled day numbers |
| `outsideDayText` | Days from neighbouring months |
| `rangeBand` | Range highlight band |
| `dot` | Marked-date dots |
| `dayLabel` | Marked-date label text |
| `gridCell` / `gridCellText` | Month and year grid cells (quick jump) |

### Props

`DatePicker` accepts everything below plus `display`. With `display="wheel"`, see [DateWheelPicker](./date-wheel-picker) instead.

#### Selection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `display` | `'calendar' \| 'wheel'` | `'calendar'` | `DatePicker` only. |
| `mode` | `'single' \| 'range' \| 'multiple' \| 'ranges'` | `'single'` | Selection mode; changes the type of `value`. |
| `value` | `Date \| null` · `DateRange` · `Date[]` · `DateRange[]` | — | Selection (controlled), typed by `mode`. |
| `defaultValue` | same as `value` | `null` · `{start:null,end:null}` · `[]` · `[]` | Initial selection when uncontrolled. |
| `onChange` | `(date: Date) => void` · `(range: DateRange) => void` · `(dates: Date[]) => void` · `(ranges: DateRange[]) => void` | — | Fires on every tap that changes the selection. |
| `minRangeDays` | `number` | — | `range` and `ranges`. See [range](./date-range-picker#props). |
| `maxRangeDays` | `number` | — | `range` and `ranges`. |
| `allowSingleDayRange` | `boolean` | `true` | `range` and `ranges`. |
| `maxSelections` | `number` | — | `multiple` only. |
| `maxRanges` | `number` | — | `ranges` only. |

#### Calendar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `minDate` | `Date` | — | Earliest selectable day. |
| `maxDate` | `Date` | — | Latest selectable day. |
| `isDateDisabled` | `(date: Date) => boolean` | — | Return `true` to disable a day. |
| `markedDates` | `Record<string, MarkedDate>` | — | Keyed by `YYYY-MM-DD`: `{ dots?, label?, textColor?, disabled? }`. |
| `locale` | `string` | device | Month / weekday names and default first day. |
| `firstDayOfWeek` | `number` (0–6) | from locale, else `0` | 0 = Sunday … 6 = Saturday. |
| `initialMonth` | `Date` | selected date or today | Month shown first. |
| `onMonthChange` | `(month: Date) => void` | — | Fires with the first day of the new month. |
| `showOutsideDays` | `boolean` | `true` | Show neighbouring months' days. |
| `fixedWeeks` | `boolean` | `true` | Always 6 rows. |
| `enableSwipe` | `boolean` | `true` | Swipe horizontally to change months. |
| `enableQuickJump` | `boolean` | `true` | Tap the title to cycle days → months → years. |
| `weekdayFormat` | `'short' \| 'narrow'` | `'short'` | `Mon` vs `M`. |
| `showWeekdays` | `boolean` | `true` | Show the weekday header. |
| `formatTitle` | `(month: Date, locale?: string) => string` | `"October 2026"` | Custom title text. |
| `renderDay` | `(state: DayState, theme: PickerTheme) => ReactNode` | — | Custom day cell content. |
| `renderArrow` | `(direction: 'prev' \| 'next', disabled: boolean) => ReactNode` | — | Custom arrows. |
| `yearRange` | `[number, number]` | min/max or ±100 years | Years available in the year grid. |
| `dayHeight` | `number` | `44` | Height of a day row. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<CalendarSlot>` | — | See [slots](#slots). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. |

#### Types

```ts
interface DateRange { start: Date | null; end: Date | null }
interface MarkedDate { dots?: string[]; disabled?: boolean; label?: string; textColor?: string }
type CalendarProps = CalendarBaseProps & CalendarSelectionProps;
type DatePickerProps = ({ display?: 'calendar' } & CalendarProps) | ({ display: 'wheel' } & DateWheelPickerProps);
```

### Accessibility

Each day is a button whose label is the full date ("Wednesday, October 14, 2026") with `selected` / `disabled` state. The arrows are labelled "Previous" / "Next", and the title is a button when quick jump is on.

### In a form field

`DatePickerField` is a field that opens a [`DatePickerSheet`](./picker-sheets#datepickersheet) and shows the confirmed date:

```tsx
import { DatePickerField } from '@elik56a/react-native-pickers';

<DatePickerField label="Due date" placeholder="Pick a date" value={date} onConfirm={setDate} minDate={new Date()} />
```

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

### Related

- [Date range & multiple](./date-range-picker)
- [DatePickerSheet](./picker-sheets#datepickersheet)
- [DatePickerField](./picker-fields): the calendar behind a form field
- [Booking recipe](../recipes/booking-range)

---

## React Native Date Range Picker

## Date range & multiple dates

Pick a check-in / check-out date range, several ranges, or several separate dates, in React Native. `DatePicker` (and `Calendar`) switch selection model with `mode`. TypeScript narrows `value` and `onChange` for each mode.

| `mode` | `value` | `onChange` | Extra props |
| --- | --- | --- | --- |
| `'single'` (default) | `Date \| null` | `(date: Date) => void` | — |
| `'range'` | `DateRange` (`{ start: Date \| null; end: Date \| null }`) | `(range: DateRange) => void` | `minRangeDays`, `maxRangeDays`, `allowSingleDayRange` |
| `'multiple'` | `Date[]` | `(dates: Date[]) => void` | `maxSelections` |
| `'ranges'` | `DateRange[]` | `(ranges: DateRange[]) => void` | `maxRanges`, `minRangeDays`, `maxRangeDays`, `allowSingleDayRange` |

The modes are also exported as constants: `mode={CALENDAR_MODE.ranges}`.

### Try the props

### Range

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  const nights = range.start && range.end ? Math.round((+range.end - +range.start) / 864e5) : 0;
  return (
    <>
      <DatePicker mode="range" value={range} onChange={setRange} minDate={new Date()} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {range.start ? formatDate(range.start) : 'Check-in'} → {range.end ? formatDate(range.end) : 'Check-out'}
        {nights ? `  ·  ${nights} night${nights > 1 ? 's' : ''}` : ''}
      </Text>
    </>
  );
}
```

#### How taps work

1. **First tap** sets the start: `onChange({ start: day, end: null })`.
2. **Second tap** on or after the start sets the end: `onChange({ start, end: day })`.
3. A tap **before** the start, or any tap **after a complete range**, starts a new range from that day.

The band between start and end uses `primaryMuted`; the ends use `primary`.

#### Ranges never cross disabled days

If the days between start and the tapped day include a disabled one (from `minDate`/`maxDate`, `isDateDisabled` or `markedDates`), the tap starts a **new range** instead of producing a range that spans an unavailable night. That's exactly what booking flows need:

```tsx live
import { useState } from 'react';
import { DatePicker, toDateKey, addDays } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const today = new Date();
  const booked = new Set([toDateKey(addDays(today, 4)), toDateKey(addDays(today, 5)), toDateKey(addDays(today, 12))]);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return (
    <DatePicker
      mode="range"
      value={range}
      onChange={setRange}
      minDate={today}
      isDateDisabled={(d) => booked.has(toDateKey(d))}
    />
  );
}
```

#### Minimum and maximum length

Length is measured in **days between start and end** (nights): a range from the 10th to the 13th is 3.

| Prop | Effect when violated |
| --- | --- |
| `minRangeDays` | A second tap that would be too short is **ignored**; the start stays selected |
| `maxRangeDays` | A second tap that would be too long **starts a new range** from that day |
| `allowSingleDayRange={false}` | Tapping the start again is ignored (by default it makes a one-day range, `start === end`) |

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return (
    <>
      <Text style={{ textAlign: 'center', marginBottom: 4, color: '#6E685E' }}>Stay 2 – 7 nights</Text>
      <DatePicker mode="range" value={range} onChange={setRange} minDate={new Date()} minRangeDays={2} maxRangeDays={7} allowSingleDayRange={false} />
    </>
  );
}
```

#### Range styling

```tsx live
import { useState } from 'react';
import { DatePicker, addDays } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const t = new Date();
  const [range, setRange] = useState<DateRange>({ start: addDays(t, 2), end: addDays(t, 6) });
  return (
    <DatePicker
      mode="range"
      value={range}
      onChange={setRange}
      theme={{ colors: { primary: '#E11D48', primaryMuted: '#FFE4E6' } }}
      styles={{ selectedDay: { borderRadius: 10 }, rangeBand: { borderRadius: 0 } }}
    />
  );
}
```

### Multiple

Tap days to toggle them. `onChange` always receives the dates **sorted ascending**. With `maxSelections`, further taps on unselected days are ignored once the limit is reached (deselecting still works).

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker, formatDate } from '@elik56a/react-native-pickers';

export default function Example() {
  const [dates, setDates] = useState<Date[]>([]);
  return (
    <>
      <DatePicker mode="multiple" value={dates} onChange={setDates} maxSelections={5} minDate={new Date()} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {dates.length ? dates.map((d) => formatDate(d, undefined, { day: 'numeric', month: 'short' })).join(', ') : 'Pick up to 5 days'}
      </Text>
    </>
  );
}
```

### Multiple ranges

`mode="ranges"` picks several date ranges, e.g. blackout periods or trip legs. Each range is built with two taps, just like range mode. Tapping any day of a finished range removes it. Ranges never overlap, and `onChange` receives them **sorted by start**. The range rules (`minRangeDays`, `maxRangeDays`, `allowSingleDayRange`) apply to each range. With `maxRanges`, taps that would start another range are ignored once the limit is reached.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DatePicker, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

export default function Example() {
  const [ranges, setRanges] = useState<DateRange[]>([]);
  const short = (d: Date | null) => (d ? formatDate(d, undefined, { day: 'numeric', month: 'short' }) : '…');
  return (
    <>
      <DatePicker mode="ranges" value={ranges} onChange={setRanges} maxRanges={3} minDate={new Date()} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {ranges.length ? ranges.map((r) => `${short(r.start)} – ${short(r.end)}`).join(', ') : 'Pick up to 3 ranges'}
      </Text>
    </>
  );
}
```

### Uncontrolled

```tsx
<DatePicker mode="range" defaultValue={{ start: new Date(), end: null }} onChange={(r) => console.log(r)} />
<DatePicker mode="multiple" defaultValue={[]} onChange={(d) => console.log(d)} />
```

### In a sheet

`DatePickerSheet` disables **Done** until the range is complete (both `start` and `end`). In ranges mode, it waits until no range is half-picked.

```tsx
<DatePickerSheet
  visible={open}
  onClose={() => setOpen(false)}
  title="Your stay"
  mode="range"
  value={range}
  onConfirm={setRange}
  minDate={new Date()}
  minRangeDays={1}
/>
```

→ [DatePickerSheet](./picker-sheets#datepickersheet)

### In a form field

`DatePickerField` takes the same props without `visible`, and shows the confirmed range (`Oct 5, 2026 – Oct 9, 2026`) or dates in the field:

```tsx
<DatePickerField label="Your stay" placeholder="Add dates" mode="range" value={range} onConfirm={setRange} minDate={new Date()} />
```

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

### Props

All [calendar props](./date-picker#calendar) apply. Mode-specific props:

| Prop | Mode | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `minRangeDays` | `range`, `ranges` | `number` | — | Minimum nights (end − start in days). Shorter second taps are ignored. |
| `maxRangeDays` | `range`, `ranges` | `number` | — | Maximum nights. Longer second taps start a new range. |
| `allowSingleDayRange` | `range`, `ranges` | `boolean` | `true` | Allow `start === end`. |
| `maxSelections` | `multiple` | `number` | — | Maximum number of selected days. |
| `maxRanges` | `ranges` | `number` | — | Maximum number of ranges. |

### Working with ranges

The [date utilities](../api/date-utils) make common range checks one-liners:

```ts
import { isBetweenDays, isSameDay, compareDay, addDays } from '@elik56a/react-native-pickers';

const nights = Math.round((range.end!.getTime() - range.start!.getTime()) / 86_400_000);
const includesToday = isSameDay(range.start, new Date()) || isBetweenDays(new Date(), range.start, range.end);
const isFuture = compareDay(range.start!, new Date()) > 0;
```

---

## React Native Date Time Picker

## DateTimePicker

`DateTimePicker` is a React Native date and time picker: pick a day and a time in one control. It has two displays:

- **`wheel`** (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`**: a month grid with the time wheels under it.

```tsx
import { DateTimePicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DateTimePicker } from '@elik56a/react-native-pickers';

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

### Try the props

### Calendar display

```tsx live
import { useState } from 'react';
import { DateTimePicker } from '@elik56a/react-native-pickers';

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

Pass Calendar options (`markedDates`, `isDateDisabled`, `firstDayOfWeek`…) through `calendarProps`. The time wheels show 3 rows here to keep the control short; 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
import { useState } from 'react';
import { Text } from 'react-native';
import { DateTimePicker, addDays } from '@elik56a/react-native-pickers';

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} onChange={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} onChange={setDate} formatDay={(d) => d.toLocaleDateString('en-GB', { day: 'numeric', month: 'short' })} />
```

### In a sheet

```tsx
import { DateTimePickerSheet } from '@elik56a/react-native-pickers';

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

It takes the same props as `DateTimePicker`, plus the [sheet props](./picker-sheets). The picked value is only reported when the user taps **Done**.

### In a form field

`DateTimePickerField` opens the same sheet from a field, and shows the confirmed moment (`Oct 26, 2026, 9:30 AM`):

```tsx
import { DateTimePickerField } from '@elik56a/react-native-pickers';

<DateTimePickerField label="Reminder" placeholder="Set a reminder" value={date} onConfirm={setDate} minDate={new Date()} />
```

→ [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. |
| `onChange` | `(date: Date) => void` | — | Fires when a wheel settles or a day is tapped. Receives a **new** `Date`. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick while scrolling (haptics). |
| `display` | `'wheel' \| 'calendar'` | `'wheel'` | One row of wheels, or a calendar with time wheels under it. |
| `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` | `Partial<CalendarBaseProps>` | — | Passed to the [Calendar](./date-picker#props) (calendar display). |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` (wheel), `3` (calendar) | 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<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. The wheels get `${testID}-day`, `-hour`, `-minute`… (in the calendar display: `-calendar`, `-time-hour`…). |

---

## React Native Date Wheel Picker

## DateWheelPicker

`DateWheelPicker` is a React Native date wheel picker with day, month and year wheels, like the classic iOS date picker. Best for dates far from today (birthdays, expiry dates) where a calendar would need many taps.

```tsx
import { DateWheelPicker } from '@elik56a/react-native-pickers';
// or: <DatePicker display="wheel" … />
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { DateWheelPicker, formatDate } from '@elik56a/react-native-pickers';

export default function Example() {
  const [birthday, setBirthday] = useState(new Date(1990, 4, 17));
  return (
    <>
      <DateWheelPicker value={birthday} onChange={setBirthday} maxDate={new Date()} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>{formatDate(birthday, undefined, { dateStyle: 'long' })}</Text>
    </>
  );
}
```

`<DatePicker display="wheel" />` renders exactly this component with the same props.

### Try the props

### Column order from the locale

The order of the wheels follows the locale's date format: month / day / year for `en-US`, day / month / year for `en-GB`, `de`, `he`, `fr`, and year / month / day for `ja`, `zh`, `ko`. Override it with `order`.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { DateWheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [d, setD] = useState(new Date(2000, 0, 31));
  return (
    <View style={{ gap: 12 }}>
      <Text style={{ fontWeight: '600' }}>en-GB</Text>
      <DateWheelPicker value={d} onChange={setD} locale="en-GB" visibleItems={3} />
      <Text style={{ fontWeight: '600' }}>ja-JP</Text>
      <DateWheelPicker value={d} onChange={setD} locale="ja-JP" visibleItems={3} />
      <Text style={{ fontWeight: '600' }}>Custom order, numeric months</Text>
      <DateWheelPicker value={d} onChange={setD} order={['year', 'month', 'day']} monthFormat="numeric" visibleItems={3} />
    </View>
  );
}
```

### Month format

| `monthFormat` | Example |
| --- | --- |
| `'long'` (default) | January |
| `'short'` | Jan |
| `'numeric'` | 01 (days are zero-padded too) |

### Day clamping

When the month or year changes to one with fewer days, the day is clamped automatically: Jan 31 → February becomes Feb 28 (or 29 in leap years). The day wheel always shows exactly the days in the selected month.

### Min, max and year range

`minDate` and `maxDate` limit the selection; days and months outside the range are disabled and the value is clamped into the range. The year wheel spans `minDate`'s year to `maxDate`'s year. Without them it uses `yearRange` (default: 100 years before and after today).

```tsx live
import { useState } from 'react';
import { DateWheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [expiry, setExpiry] = useState(new Date(2028, 5, 1));
  return <DateWheelPicker value={expiry} onChange={setExpiry} order={['month', 'year']} monthFormat="numeric" yearRange={[2026, 2040]} loop={false} />;
}
```

:::tip Month + year only
Pass only the columns you need in `order`, for example `['month', 'year']` for card expiry dates. The day is kept from `value`, and clamped if needed.
:::

### Looping

The day and month wheels loop by default (`loop`); the year wheel never loops.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected date (controlled). Time of day is preserved. |
| `defaultValue` | `Date` | today | Initial date when uncontrolled (clamped to min/max). |
| `onChange` | `(date: Date) => void` | — | Fires when a wheel settles. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick (haptics). |
| `locale` | `string` | device | Month names and default column order. |
| `minDate` | `Date` | — | Earliest selectable date. |
| `maxDate` | `Date` | — | Latest selectable date. |
| `order` | `('day' \| 'month' \| 'year')[]` | from locale | Columns and their order. |
| `monthFormat` | `'long' \| 'short' \| 'numeric'` | `'long'` | Month labels. |
| `yearRange` | `[number, number]` | today ±100 | Years when no min/max is set. |
| `loop` | `boolean` | `true` | Loop day and month wheels. |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` | Visible rows. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. |

```ts
type DatePart = 'day' | 'month' | 'year';
```

### Related

- [Birthday recipe](../recipes/birthday)
- [DatePickerSheet with `display="wheel"`](./picker-sheets#datepickersheet)
- [DatePickerField with `display="wheel"`](./picker-fields): the wheel behind a form field

---

## React Native Emoji Picker

## EmojiPicker

`EmojiPicker` is a full React Native emoji keyboard: 1,906 emojis in 9 categories, keyword search, skin tones, recently used, a category bar, and filtering by Emoji version so older devices never show empty boxes. Emojis render with the system font; no images or fonts are bundled.

```tsx
import { EmojiPicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { EmojiPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [text, setText] = useState('Hello ');
  return (
    <>
      <Text style={{ fontSize: 24, minHeight: 36, marginBottom: 8 }}>{text}</Text>
      <EmojiPicker onSelect={(emoji) => setText((t) => t + emoji)} />
    </>
  );
}
```

### Try the props

<PropPlayground
  name="EmojiPicker"
  component={EmojiPicker}
  props={{ onSelect: () => {} }}
  code="onSelect={insert}"
  controls={[
    { prop: 'categoryBarPosition', options: ['top', 'bottom'] },
    { prop: 'columns', options: [6, 8, 10], default: 8 },
    { prop: 'searchable', options: [true, false] },
    { prop: 'showCategoryBar', options: [true, false] },
    { prop: 'showSectionHeaders', options: [true, false] },
    { prop: 'showSkinTones', options: [true, false] },
    { prop: 'showRecent', options: [true, false] },
  ]}
/>

### `onSelect`

```ts
onSelect: (emoji: string, data: Emoji) => void
```

`emoji` is the character to insert, **with the current skin tone applied**. `data` is the base emoji's metadata:

```ts
interface Emoji {
  emoji: string;          // base character, e.g. '👍'
  name: string;           // 'thumbs up'
  keywords: string[];     // search tags
  category: EmojiCategory;
  version: number;        // Emoji version it was introduced in, e.g. 13.1
  skins?: string[];       // 5 skin-tone variants (light → dark) when supported
}
```

### Categories

```ts
type EmojiCategory = 'smileys' | 'people' | 'animals' | 'food' | 'travel' | 'activities' | 'objects' | 'symbols' | 'flags';
```

`categories` filters **and** orders the sections and the category bar:

```tsx live
import { EmojiPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  return <EmojiPicker height={300} categories={['food', 'animals', 'activities']} onSelect={() => {}} showSkinTones={false} />;
}
```

Hide specific characters with `exclude={['🖕', '🍆']}`.

### Search

The search field matches names and keywords, ranks name-prefix matches first, and requires every word to match (`cat face` → 🐱). Search across a custom list in your own UI with [`searchEmojis`](../api/emoji-utils#searchemojis).

### Skin tones

The ✋ button next to search opens a tone menu. Tones are numbers:

```ts
type SkinTone = 0 | 1 | 2 | 3 | 4 | 5; // 0 = default yellow, 1–5 = light → dark
```

Tones apply to every emoji that supports them, in the grid and in what `onSelect` returns. Control or persist the tone:

```tsx
const [tone, setTone] = useState<SkinTone>(0);
<EmojiPicker skinTone={tone} onSkinToneChange={setTone} onSelect={insert} />
```

Use `defaultSkinTone` for uncontrolled, or `showSkinTones={false}` to hide the button.

### Recently used

Picked emojis go to a **Recently used** section at the top (up to `maxRecent`, default 24, most recent first). The list stores **base** emojis, so they re-render in whatever tone is current.

The picker keeps recents in memory by default. To persist them across launches, control them:

```tsx title="Persisting recents with AsyncStorage"
import AsyncStorage from '@react-native-async-storage/async-storage';

function Picker({ onPick }: { onPick: (e: string) => void }) {
  const [recent, setRecent] = useState<string[]>([]);

  useEffect(() => {
    AsyncStorage.getItem('emoji-recent').then((v) => v && setRecent(JSON.parse(v)));
  }, []);

  return (
    <EmojiPicker
      recent={recent}
      onRecentChange={(next) => {
        setRecent(next);
        AsyncStorage.setItem('emoji-recent', JSON.stringify(next));
      }}
      onSelect={onPick}
    />
  );
}
```

Seed a starter set with `defaultRecent={['👍', '❤️', '😂']}`, or turn the section off with `showRecent={false}`.

### Older devices: `maxEmojiVersion`

Emojis newer than the device's font render as empty boxes (common on older Android). Hide them by version:

```tsx
import { Platform } from 'react-native';

<EmojiPicker
  maxEmojiVersion={Platform.OS === 'android' && Platform.Version < 30 ? 12 : undefined}
  onSelect={insert}
/>
```

### Layout

```tsx live
import { EmojiPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  return (
    <EmojiPicker
      height={340}
      columns={7}
      emojiSize={30}
      categoryBarPosition="bottom"
      showSectionHeaders={false}
      onSelect={() => {}}
    />
  );
}
```

- `columns` (default 8) sets emojis per row. Cells are square and fill the width.
- `emojiSize` sets the font size (default about 62% of the cell).
- `height` (default 380) is the total height including search and category bar.
- `categoryBarPosition`: `'top'` (default) or `'bottom'`. Hide the bar with `showCategoryBar={false}`.
- `showSectionHeaders={false}` removes the "Smileys & Emotion" style headers.

### Translating labels and icons

Every label is replaceable. The `categoryLabels` keys are the categories plus `recent` and `search`. Icons can be strings (rendered as text) or any React node:

```tsx live
import { EmojiPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  return (
    <EmojiPicker
      height={320}
      searchPlaceholder="Rechercher"
      emptyText="Aucun emoji"
      categoryLabels={{
        recent: 'Récents',
        smileys: 'Smileys et émotions',
        people: 'Personnes',
        animals: 'Animaux et nature',
        food: 'Nourriture',
        travel: 'Voyages',
        activities: 'Activités',
        objects: 'Objets',
        symbols: 'Symboles',
        flags: 'Drapeaux',
        search: 'Résultats',
      }}
      categoryIcons={{ smileys: '🙂', food: '🥐' }}
      onSelect={() => {}}
    />
  );
}
```

### Custom emoji cells

`renderEmoji(emoji, data, size)` replaces the character, for example to render a custom image set like Twemoji:

```tsx
<EmojiPicker
  renderEmoji={(emoji, data, size) => <Image source={{ uri: twemojiUrl(emoji) }} style={{ width: size, height: size }} />}
  onSelect={insert}
/>
```

### In a sheet

```tsx
<EmojiPickerSheet visible={open} onClose={() => setOpen(false)} onSelect={(e) => setText((t) => t + e)} />
```

The sheet closes after each pick by default (`closeOnSelect={false}` to keep it open). → [EmojiPickerSheet](./picker-sheets#emojipickersheet)

### In a form field

`EmojiPickerField` opens the sheet from a field and shows `value`, the emoji you keep in state. Use `renderTrigger` for an icon button instead of a field:

```tsx
import { EmojiPickerField } from '@elik56a/react-native-pickers';

<EmojiPickerField label="Icon" placeholder="Pick an icon" value={icon} onSelect={setIcon} />
```

→ [Picker fields](./picker-fields#custom-trigger)

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `(emoji: string, data: Emoji) => void` | **required** | Called with the toned character and its metadata. |
| `columns` | `number` | `8` | Emojis per row. |
| `emojiSize` | `number` | ~62% of cell | Emoji font size. |
| `height` | `number` | `380` | Total height. |
| `categories` | `EmojiCategory[]` | all 9 | Which categories to show, in order. |
| `exclude` | `string[]` | — | Characters to hide. |
| `maxEmojiVersion` | `number` | — | Hide emojis newer than this Emoji version. |
| `searchable` | `boolean` | `true` | Show the search field. |
| `searchPlaceholder` | `string` | `'Search emoji'` | Search hint. |
| `emptyText` | `string` | `'No emoji found'` | Empty search result text. |
| `showCategoryBar` | `boolean` | `true` | Show the category tabs. |
| `categoryBarPosition` | `'top' \| 'bottom'` | `'top'` | Tab bar position. |
| `showSectionHeaders` | `boolean` | `true` | Section title rows. |
| `categoryLabels` | `Partial<Record<EmojiCategory \| 'recent' \| 'search', string>>` | English | Section and tab labels. |
| `categoryIcons` | `Partial<Record<EmojiCategory \| 'recent', ReactNode>>` | emoji icons | Tab icons. |
| `skinTone` | `SkinTone` | — | Controlled tone. |
| `defaultSkinTone` | `SkinTone` | `0` | Initial tone. |
| `onSkinToneChange` | `(tone: SkinTone) => void` | — | Tone picked in the menu. |
| `showSkinTones` | `boolean` | `true` | Show the tone button. |
| `recent` | `string[]` | — | Controlled recents (base characters). |
| `defaultRecent` | `string[]` | `[]` | Initial recents. |
| `onRecentChange` | `(recent: string[]) => void` | — | New recents after each pick. |
| `showRecent` | `boolean` | `true` | Show and update recents. |
| `maxRecent` | `number` | `24` | Recents kept. |
| `renderEmoji` | `(emoji: string, data: Emoji, size: number) => ReactNode` | — | Custom cell content. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<EmojiPickerSlot>` | — | Slots below. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. |

#### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `header` | Search + tone row |
| `searchInput` | Search `TextInput` |
| `skinToneButton` / `skinToneMenu` | Tone button / menu |
| `categoryBar` | Tab bar |
| `categoryTab` / `activeCategoryTab` | Tabs |
| `categoryIndicator` | Active-tab underline |
| `sectionHeader` / `sectionHeaderText` | Section titles |
| `emojiCell` / `emojiText` | Grid cells |
| `empty` / `emptyText` | No search results |

### Data and utilities

The emoji data comes from [emojibase](https://emojibase.dev) (MIT) and is parsed lazily on first use. The helpers are exported for your own UIs (reactions bars, `:shortcode` autocomplete): `getAllEmojis`, `searchEmojis`, `findEmoji`, `withSkinTone`, `EMOJI_CATEGORIES`, `DEFAULT_CATEGORY_LABELS`, `DEFAULT_CATEGORY_ICONS`. → [Emoji utilities](../api/emoji-utils)

### Related

- [Chat input recipe](../recipes/chat-emoji)
- [EmojiPickerField](./picker-fields): the picker behind a form field

---

## React Native Multi-Column Wheel Picker

## MultiWheelPicker

`MultiWheelPicker` puts several React Native [`WheelPicker`](./wheel-picker)s side by side, sharing **one** selection band, the way iOS shows time and date wheels. `TimePicker` and `DateWheelPicker` are built on it. Use it for durations, heights, weights, currency + amount, or anything multi-column.

```tsx
import { MultiWheelPicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { MultiWheelPicker } from '@elik56a/react-native-pickers';

const range = (n: number) => Array.from({ length: n }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i }));

export default function Example() {
  const [h, setH] = useState(1);
  const [m, setM] = useState(30);
  const [s, setS] = useState(0);
  return (
    <MultiWheelPicker
      separator=":"
      columns={[
        { key: 'h', items: range(24), value: h, onChange: setH },
        { key: 'm', items: range(60), value: m, onChange: setM, loop: true },
        { key: 's', items: range(60), value: s, onChange: setS, loop: true },
      ]}
    />
  );
}
```

### Try the props

<PropPlayground
  name="MultiWheelPicker"
  component={MultiWheelPicker}
  props={{
    separator: ':',
    columns: [
      { key: 'h', items: Array.from({ length: 24 }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i })), defaultValue: 9 },
      { key: 'm', items: Array.from({ length: 60 }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i })), defaultValue: 41, loop: true },
    ],
  }}
  code="columns={columns} separator=&quot;:&quot;"
  controls={[
    { prop: 'variant', options: ['3d', 'flat'] },
    { prop: 'visibleItems', options: [3, 5, 7], default: 5 },
    { prop: 'itemHeight', options: [32, 40, 52], default: 40 },
  ]}
/>

### Columns

Each entry in `columns` is a `WheelPicker`'s props (minus the shared ones below) plus layout keys:

```ts
type WheelColumn<T> = Omit<WheelPickerProps<T>, 'itemHeight' | 'visibleItems' | 'variant' | 'showIndicator' | 'theme'> & {
  key: string;     // React key, required
  flex?: number;   // flex weight, default 1
  width?: number;  // fixed width instead of flex
};
```

So every column has its own `items`, `value`, `onChange`, `onValueChanging`, `loop`, `renderItem`, `keyboardInput`, `isEqual`, `textAlign`, `disabled`, `styles` and so on. `itemHeight`, `visibleItems`, `variant` and `theme` are set once on the `MultiWheelPicker` so all columns line up.

### Labels and separators

`separator` is placed between every pair of columns. A string is rendered as bold text (style it with the `separator` slot), and any React node is rendered as-is. Pass a function to choose per gap: it gets the index of the column on the left and can return `null` to skip that gap.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { MultiWheelPicker } from '@elik56a/react-native-pickers';

const feet = [3, 4, 5, 6, 7].map((v) => ({ label: `${v} ft`, value: v }));
const inches = Array.from({ length: 12 }, (_, i) => ({ label: `${i} in`, value: i }));

export default function Example() {
  const [ft, setFt] = useState(5);
  const [inch, setInch] = useState(9);
  return (
    <>
      <MultiWheelPicker
        columns={[
          { key: 'ft', items: feet, value: ft, onChange: setFt, textAlign: 'right' },
          { key: 'in', items: inches, value: inch, onChange: setInch, textAlign: 'left' },
        ]}
      />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {ft}′{inch}″ = {Math.round((ft * 12 + inch) * 2.54)} cm
      </Text>
    </>
  );
}
```

### Column widths

Use `flex` for proportional columns and `width` for fixed ones:

```tsx live
import { useState } from 'react';
import { MultiWheelPicker } from '@elik56a/react-native-pickers';

const amounts = Array.from({ length: 100 }, (_, i) => (i + 1) * 10);

export default function Example() {
  const [cur, setCur] = useState('USD');
  const [amount, setAmount] = useState(250);
  return (
    <MultiWheelPicker
      variant="flat"
      columns={[
        { key: 'cur', items: ['USD', 'EUR', 'GBP', 'ILS'], value: cur, onChange: setCur, width: 90 },
        { key: 'amount', items: amounts, value: amount, onChange: setAmount, flex: 2 },
      ]}
    />
  );
}
```

### Dependent columns

Columns are plain props, so derive one from another in render. Here the model list depends on the brand:

```tsx live
import { useState } from 'react';
import { MultiWheelPicker } from '@elik56a/react-native-pickers';

const models: Record<string, string[]> = {
  Apple: ['iPhone 15', 'iPhone 16', 'iPhone 17'],
  Google: ['Pixel 8', 'Pixel 9', 'Pixel 10'],
  Samsung: ['Galaxy S24', 'Galaxy S25', 'Galaxy Z Fold'],
};

export default function Example() {
  const [brand, setBrand] = useState('Google');
  const [model, setModel] = useState('Pixel 9');
  return (
    <MultiWheelPicker
      columns={[
        {
          key: 'brand',
          items: Object.keys(models),
          value: brand,
          onChange: (b) => {
            setBrand(b);
            setModel(models[b][0]);
          },
        },
        { key: 'model', items: models[brand], value: model, onChange: setModel, flex: 1.4 },
      ]}
    />
  );
}
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `WheelColumn[]` | **required** | One entry per wheel; see [Columns](#columns). |
| `separator` | `ReactNode \| ((leftIndex: number) => ReactNode)` | — | Content between columns. Strings use the `separator` slot style. |
| `itemHeight` | `number` | `40` | Row height shared by all columns. |
| `visibleItems` | `number` | `5` | Visible rows (odd) shared by all columns. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style for all columns. |
| `style` | `StyleProp<ViewStyle>` | — | Outer container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | Slot styles, applied to every column (a column's own `styles` win). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override for all columns. |
| `testID` | `string` | — | Test ID on the container. |

#### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `indicator` | The shared selection band |
| `separator` | String separators |
| `item`, `itemText`, `selectedItemText`, `disabledItemText` | Forwarded to every column's wheel |

```ts
type MultiWheelSlot = 'container' | 'indicator' | 'separator' | WheelPickerSlot;
```

### Related

- [TimePicker](./time-picker) and [DateWheelPicker](./date-wheel-picker) are pre-built `MultiWheelPicker`s
- [Duration recipe](../recipes/duration)

---

## React Native Date, Time & Wheel Picker Fields

## Picker fields

In a form, a picker usually isn't on screen. The user taps a field, picks in a sheet, and sees the value in the field once the sheet closes. Each picker has a field that does this, with the same look as [`SelectPicker`](./select-picker)'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` |
| `DateTimePickerField` | [`DateTimePickerSheet`](./date-time-picker#in-a-sheet) | `Oct 26, 2026, 9:30 AM` |
| `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 '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { DatePickerField, DateTimePickerField, EmojiPickerField, SelectPicker, TimePickerField, WheelPickerField } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

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} />
      <SelectPicker label="Room" placeholder="Choose a room" options={rooms} value={room} onChange={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 `visible`, 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.

### Try the props

### What the field shows

Dates and times are formatted with `Intl` for the field's `locale` (the device locale by default). `TimePickerField` 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…'`).

### Label and sheet title

`label` is drawn above the field, used as its accessibility label and, unless you set `title`, as the sheet's 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)} />
```

### Custom trigger

`renderTrigger` replaces the field box, and gets `{ open, displayValue, disabled }`. The label still renders above it, and the sheet still opens from the field.

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { EmojiPickerField } from '@elik56a/react-native-pickers';

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 [SelectPicker](./select-picker#custom-chevron).

### Your own sheet: `PickerField`

`PickerField` is the field without a picker. Its child is a function that gets `{ visible, onClose }` for the sheet you render, so any [`BottomSheet`](./bottom-sheet) or [`PickerSheet`](./picker-sheets#pickersheet) can open from a field.

```tsx live
import { useState } from 'react';
import { Switch, Text, View } from 'react-native';
import { PickerField, PickerSheet, useDraft } from '@elik56a/react-native-pickers';

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

const NotificationsSheet = ({ visible, onClose, prefs, onSave }: { visible: boolean; onClose: () => void; prefs: Prefs; onSave: (p: Prefs) => void }) => {
  const [draft, setDraft] = useDraft(prefs, visible);
  return (
    <PickerSheet
      visible={visible}
      onClose={onClose}
      title="Notifications"
      confirmLabel="Save"
      onConfirm={() => {
        onSave(draft);
        onClose();
      }}
    >
      <View style={{ padding: 16, gap: 16 }}>
        {(['push', 'email'] as const).map((k) => (
          <View key={k} style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
            <Text style={{ fontSize: 16, textTransform: 'capitalize' }}>{k}</Text>
            <Switch value={draft[k]} onValueChange={(v) => setDraft({ ...draft, [k]: v })} />
          </View>
        ))}
      </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` | Label text above the field |
| `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) |
| `clear` | × button text |

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

### Props

Every field takes these, plus its sheet's props without `visible`: `value`, `onConfirm` (`onSelect` for emoji), `title`, `presentation`, `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. 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. |
| `renderTrigger` | `(info: { open, displayValue, disabled }) => ReactNode` | — | Replace the field box. |
| `renderChevron` | `(info: { open, theme }) => ReactNode` | — | Custom chevron icon. It still rotates on open and close. |
| `onOpen` / `onClose` | `() => void` | — | The sheet opened / closed (Done, Cancel or dismiss). |
| `style` | `StyleProp<ViewStyle>` | — | Wrapper style (label + field). |
| `styles` | `SlotStyles<PickerFieldSlot \| …>` | — | Field slots plus the picker's slots. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme for the field and the sheet. |
| `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) and `children: (sheet: { visible, onClose }) => ReactNode`.

#### Types

```ts
import type {
  DatePickerFieldProps,
  TimePickerFieldProps,
  DateTimePickerFieldProps,
  WheelPickerFieldProps,
  EmojiPickerFieldProps,
  PickerFieldProps,
  PickerFieldBaseProps,
  PickerFieldSlot,
  PickerFieldTriggerInfo,
  WithPickerField,
} from '@elik56a/react-native-pickers';
```

`WithPickerField<SheetProps, Slot>` turns a sheet's props into a field's, for wrapping your own sheet the same way.

### 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 sheet is open. The × button is labelled `Clear`.

### Related

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

---

## React Native Bottom Sheet Pickers

## Picker sheets

Every React Native picker in this library is also available inside a [`BottomSheet`](./bottom-sheet) with a **Cancel / Done** header. They all share the same "chrome" props and the same draft behaviour.

:::tip Opening a sheet from a form field?
You don't need your own button and `visible` state. [Picker fields](./picker-fields) (`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField`, `EmojiPickerField`) take the same props without `visible`/`onClose`, render a field that opens the sheet, and show the confirmed value.
:::

### Inline, bottom sheet or modal

Every picker can be shown three ways:

- **Inline:** the plain component (`WheelPicker`, `TimePicker`, `DatePicker`, `SelectList`, `EmojiPicker`) renders in place.
- **Bottom sheet:** slides up from the bottom and can be dragged down to dismiss.
- **Modal:** a centered dialog.

Each sheet can also open from a [field](./picker-fields) that shows the picked value.

The sheets take `presentation`: `'auto'` (default), `'bottomSheet'` or `'modal'`. `auto` is a modal on web windows wider than the sheet, where a bottom sheet would look cut off, and a bottom sheet on phones and native.

```tsx
<TimePickerSheet presentation="modal" visible={open} onClose={close} value={time} onConfirm={setTime} />
```

[`SelectPicker`](./select-picker#presentation) also supports `'dropdown'`, which opens under the field. It's `SelectPicker`'s default on the web.

```tsx
import { DatePickerSheet, TimePickerSheet, WheelPickerSheet, EmojiPickerSheet, PickerSheet, useDraft } from '@elik56a/react-native-pickers';
```

### Try the props

### How drafts work

1. When the sheet **opens**, it copies `value` into a draft.
2. The picker inside edits only the draft.
3. **Done** calls `onConfirm(draft)` and then `onClose()`.
4. **Cancel**, a backdrop tap, a swipe down or Android back calls only `onClose()`, and the draft is thrown away.

Your state changes only when the user confirms, which is how native iOS / Android pickers behave.

### Shared props

All sheets accept these (`SheetChromeProps`):

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` | **required** | Show / hide. |
| `onClose` | `() => void` | **required** | Set `visible` to `false` here. |
| `title` | `ReactNode` | — | Header title. |
| `confirmLabel` | `string` | `'Done'` | Confirm button text. |
| `cancelLabel` | `string` | `'Cancel'` | Cancel button text. |
| `showCancel` | `boolean` | `true` (`false` for emoji) | Show the Cancel button. |
| `presentation` | `'auto' \| 'bottomSheet' \| 'modal'` | `'auto'` | Bottom sheet or centered modal. `auto`: modal on wide web windows, bottom sheet elsewhere. |
| `sheetProps` | `Partial<BottomSheetProps>` | — | Passed to the [BottomSheet](./bottom-sheet#props) (`height`, `bottomInset`, `styles`, `enableSwipeToClose`…). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme for the sheet and the picker. |

---

### DatePickerSheet

A calendar (single, range, multiple) or date wheel in a sheet.

```tsx live
import { useState } from 'react';
import { Pressable, Text, View } from 'react-native';
import { DatePickerSheet, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

function Field({ label, value, onPress }: { label: string; value: string; onPress: () => void }) {
  return (
    <Pressable onPress={onPress} style={{ borderWidth: 1, borderColor: '#E8E4DC', borderRadius: 12, padding: 14 }}>
      <Text style={{ fontSize: 12, color: '#6E685E' }}>{label}</Text>
      <Text style={{ fontSize: 16, marginTop: 2 }}>{value}</Text>
    </Pressable>
  );
}

export default function Example() {
  const [sheet, setSheet] = useState<'day' | 'range' | 'birthday' | null>(null);
  const [day, setDay] = useState<Date | null>(null);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  const [birthday, setBirthday] = useState(new Date(1995, 6, 12));
  const close = () => setSheet(null);
  return (
    <View style={{ gap: 10 }}>
      <Field label="Delivery date" value={day ? formatDate(day) : 'Choose…'} onPress={() => setSheet('day')} />
      <Field
        label="Trip"
        value={range.start && range.end ? `${formatDate(range.start)} → ${formatDate(range.end)}` : 'Choose…'}
        onPress={() => setSheet('range')}
      />
      <Field label="Birthday" value={formatDate(birthday)} onPress={() => setSheet('birthday')} />

      <DatePickerSheet visible={sheet === 'day'} onClose={close} title="Delivery" value={day} onConfirm={setDay} minDate={new Date()} confirmOnSelect />
      <DatePickerSheet visible={sheet === 'range'} onClose={close} title="Trip dates" mode="range" value={range} onConfirm={setRange} minDate={new Date()} />
      <DatePickerSheet visible={sheet === 'birthday'} onClose={close} title="Birthday" display="wheel" value={birthday} onConfirm={setBirthday} maxDate={new Date()} />
    </View>
  );
}
```

#### Behaviour

- **Done is disabled** until the selection is complete: a date in single mode, both `start` and `end` in range mode, no half-picked range in ranges mode. Multiple and ranges modes can confirm an empty array.
- **`confirmOnSelect`** (single + calendar only) hides Done and confirms as soon as a day is tapped.
- **`display="wheel"`** shows a [DateWheelPicker](./date-wheel-picker) (single mode). The draft starts at `value` or today. `locale`, `minDate` and `maxDate` are forwarded; pass other wheel props via `wheelProps`.

#### Props

Shared props, plus every [calendar prop](./date-picker#calendar) (`minDate`, `maxDate`, `isDateDisabled`, `markedDates`, `locale`, `firstDayOfWeek`, `styles`, `renderDay`…), plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'single' \| 'range' \| 'multiple' \| 'ranges'` | `'single'` | Selection mode. |
| `value` | `Date \| null` · `DateRange` · `Date[]` · `DateRange[]` | — | Current committed value; copied into the draft on open. |
| `onConfirm` | `(date: Date)` · `(range: DateRange)` · `(dates: Date[])` · `(ranges: DateRange[])` `=> void` | **required** | Called with the draft on Done. |
| `minRangeDays` / `maxRangeDays` | `number` | — | Range and ranges modes. |
| `maxSelections` | `number` | — | Multiple mode. |
| `maxRanges` | `number` | — | Ranges mode. |
| `display` | `'calendar' \| 'wheel'` | `'calendar'` | Wheel is single mode only. |
| `wheelProps` | `Partial<DateWheelPickerProps>` | — | Extra props for the wheel. |
| `confirmOnSelect` | `boolean` | `false` | Single calendar: confirm on tap, no Done button. |

---

### TimePickerSheet

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { TimePickerSheet } from '@elik56a/react-native-pickers';

export default function Example() {
  const [open, setOpen] = useState(false);
  const [time, setTime] = useState(new Date(2026, 0, 1, 7, 30));
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ alignItems: 'center', padding: 12 }}>
        <Text style={{ fontSize: 48, fontWeight: '200' }}>{time.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}</Text>
        <Text style={{ color: '#C8460D' }}>Change</Text>
      </Pressable>
      <TimePickerSheet visible={open} onClose={() => setOpen(false)} title="Wake up" value={time} onConfirm={setTime} minuteInterval={5} />
    </>
  );
}
```

Props: shared props, every [TimePicker prop](./time-picker#props) except `value`/`defaultValue`/`onChange`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | now | Copied into the draft on open. |
| `onConfirm` | `(date: Date) => void` | **required** | Called with the draft on Done. |

---

### WheelPickerSheet

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { WheelPickerSheet } from '@elik56a/react-native-pickers';

const guests = Array.from({ length: 12 }, (_, i) => ({ label: `${i + 1} guest${i ? 's' : ''}`, value: i + 1 }));

export default function Example() {
  const [open, setOpen] = useState(false);
  const [count, setCount] = useState(2);
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ borderWidth: 1, borderColor: '#E8E4DC', borderRadius: 12, padding: 14 }}>
        <Text>👥 {guests[count - 1].label}</Text>
      </Pressable>
      <WheelPickerSheet visible={open} onClose={() => setOpen(false)} title="Guests" items={guests} value={count} onConfirm={setCount} />
    </>
  );
}
```

Props: shared props, every [WheelPicker prop](./wheel-picker#props) except `value`/`defaultValue`/`onChange`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `T` | first item | Copied into the draft on open. |
| `onConfirm` | `(value: T) => void` | **required** | Called with the draft on Done. |

---

### EmojiPickerSheet

No Done button: each pick calls `onSelect`, and the sheet closes unless `closeOnSelect={false}`.

```tsx live
import { useState } from 'react';
import { Pressable, Text, View } from 'react-native';
import { EmojiPickerSheet } from '@elik56a/react-native-pickers';

export default function Example() {
  const [open, setOpen] = useState(false);
  const [reactions, setReactions] = useState(['👍', '🎉']);
  return (
    <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
      {reactions.map((r, i) => (
        <Text key={i} style={{ fontSize: 22, backgroundColor: '#F4F2EE', borderRadius: 999, paddingHorizontal: 10, paddingVertical: 4 }}>{r}</Text>
      ))}
      <Pressable onPress={() => setOpen(true)} style={{ borderRadius: 999, borderWidth: 1, borderColor: '#E8E4DC', paddingHorizontal: 12, justifyContent: 'center' }}>
        <Text>＋</Text>
      </Pressable>
      <EmojiPickerSheet visible={open} onClose={() => setOpen(false)} title="React" onSelect={(e) => setReactions((r) => [...r, e])} />
    </View>
  );
}
```

Props: shared props, every [EmojiPicker prop](./emoji-picker#props), plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnSelect` | `boolean` | `true` | Close after a pick. |
| `height` | `number` | `420` | Picker height inside the sheet. |
| `showCancel` | `boolean` | `false` | Show a Cancel button. |

---

### PickerSheet

The building block: a `BottomSheet` with Cancel on the left and (when you pass `onConfirm`) Done on the right. Use it to build sheets for your own pickers.

```tsx live
import { useState } from 'react';
import { Pressable, Text, Switch, View } from 'react-native';
import { PickerSheet, useDraft } from '@elik56a/react-native-pickers';

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

export default function Example() {
  const [open, setOpen] = useState(false);
  const [prefs, setPrefs] = useState<Prefs>({ push: true, email: false });
  const [draft, setDraft] = useDraft(prefs, open);
  return (
    <>
      <Pressable onPress={() => setOpen(true)} style={{ padding: 14, borderRadius: 12, backgroundColor: '#F4F2EE' }}>
        <Text>Notifications: {[prefs.push && 'push', prefs.email && 'email'].filter(Boolean).join(' + ') || 'off'}</Text>
      </Pressable>
      <PickerSheet
        visible={open}
        onClose={() => setOpen(false)}
        title="Notifications"
        confirmLabel="Save"
        onConfirm={() => {
          setPrefs(draft);
          setOpen(false);
        }}
      >
        <View style={{ padding: 16, gap: 16 }}>
          {(['push', 'email'] as const).map((k) => (
            <View key={k} style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
              <Text style={{ fontSize: 16, textTransform: 'capitalize' }}>{k}</Text>
              <Switch value={draft[k]} onValueChange={(v) => setDraft({ ...draft, [k]: v })} />
            </View>
          ))}
        </View>
      </PickerSheet>
    </>
  );
}
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | **required** | Sheet content. |
| `onConfirm` | `() => void` | — | Shows the confirm button. **You** close the sheet (call `onClose` / set `visible`). |
| `confirmDisabled` | `boolean` | `false` | Disable the confirm button. |
| …shared props | | | `visible`, `onClose`, `title`, `confirmLabel`, `cancelLabel`, `showCancel`, `sheetProps`, `theme`. |

### `useDraft`

```ts
function useDraft<V>(value: V, visible: boolean): [draft: V, setDraft: (v: V) => void];
```

Returns a draft copy of `value` that **resets to `value` each time `visible` turns true**. It's the hook the built-in sheets use; use it for your own `PickerSheet`s as shown above.

---

## React Native Searchable Select List

## SelectList

`SelectList` is the searchable React Native list inside [`SelectPicker`](./select-picker), as a standalone inline component. Use it in settings screens, onboarding steps, or your own sheets and modals.

```tsx
import { SelectList } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { SelectList } from '@elik56a/react-native-pickers';

const themes = [
  { label: 'System', value: 'system', description: 'Follow the device setting' },
  { label: 'Light', value: 'light' },
  { label: 'Dark', value: 'dark' },
];

export default function Example() {
  const [mode, setMode] = useState<string | null>('system');
  return (
    <View style={{ borderWidth: 1, borderColor: '#E8E4DC', borderRadius: 16, paddingVertical: 8 }}>
      <SelectList options={themes} value={mode} onChange={setMode} />
    </View>
  );
}
```

### Try the props

<PropPlayground
  name="SelectList"
  component={SelectList}
  props={{
    listHeight: 260,
    options: ['Canada', 'France', 'Germany', 'Israel', 'Italy', 'Japan', 'Mexico', 'Spain', 'Sweden', 'United States'].map((c) => ({ label: c, value: c })),
  }}
  value={(p) => (p.multiple ? ['Japan'] : 'Japan')}
  code="options={countries} value={value} onChange={setValue}"
  controls={[
    { prop: 'multiple', options: [false, true] },
    { prop: 'searchable', options: [true, false], default: null },
    { prop: 'showCheckmarks', options: [true, false] },
  ]}
/>

### Multiple, with search

```tsx live
import { useState } from 'react';
import { SelectList } from '@elik56a/react-native-pickers';

const toppings = ['Mozzarella', 'Basil', 'Mushrooms', 'Olives', 'Pepperoni', 'Jalapeños', 'Pineapple', 'Onion', 'Ham', 'Rocket'].map((t) => ({
  label: t,
  value: t,
  group: ['Pepperoni', 'Ham'].includes(t) ? 'Meat' : 'Veggie',
}));

export default function Example() {
  const [picked, setPicked] = useState<string[]>(['Mozzarella', 'Basil']);
  return <SelectList multiple options={toppings} value={picked} onChange={setPicked} maxSelected={5} listHeight={320} />;
}
```

### Behaviour

- **Controlled only**: pass `value` and update it in `onChange`.
- In single mode, tapping an option calls `onChange(value, option)`, including when it's already selected (there's no deselect).
- In multiple mode, taps toggle. `onChange(values, options)` keeps selection order (appended at the end).
- With `maxSelected` reached, unselected options become disabled until something is deselected.
- Without `listHeight`, the list grows with its content. Inside a scroll view or sheet, give it a `listHeight` so it scrolls on its own.
- Search state is internal and resets when the list unmounts.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `ReadonlyArray<SelectOption<T>>` | **required** | See [options](./select-picker#options). |
| `multiple` | `boolean` | `false` | Multi-select. |
| `value` | `T \| null` · `T[]` | — | Selection. |
| `onChange` | `(value: T, option) => void` · `(values: T[], options) => void` | — | Single · multiple. |
| `maxSelected` | `number` | — | Multiple only. |
| `searchable` | `boolean` | `options.length > 8` | Show the search field. |
| `query` | `string` | — | Controlled search query, for filtering from your own input. Hides the built-in search field. |
| `searchPlaceholder` | `string` | `'Search'` | Search hint and its accessibility label. |
| `filterOption` | `(option: SelectOption<T>, query: string) => boolean` | `defaultFilter` | Custom filter. |
| `renderOption` | `(info: SelectRenderOptionInfo<T>) => ReactNode` | — | Custom row content. |
| `renderGroupHeader` | `(group: string, theme: PickerTheme) => ReactNode` | — | Custom section header. |
| `emptyText` | `string` | `'No results'` | Empty-state text. |
| `showCheckmarks` | `boolean` | `true` | ✓ (single) / checkbox (multiple). |
| `isEqual` | `(a: T, b: T) => boolean` | `Object.is` | Value equality. |
| `listHeight` | `number` | — | Fixed height for the scrolling list. |
| `autoFocusSearch` | `boolean` | `false` | Focus the search on mount. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<SelectSlot>` | — | Slots below. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. |

#### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `search` | Search field wrapper |
| `searchInput` | The `TextInput` |
| `list` | The `FlatList` |
| `groupHeader` / `groupHeaderText` | Section header |
| `option` | Each row |
| `selectedOption` | Selected rows (merged after `option`) |
| `optionLabel` / `selectedOptionLabel` | Row label |
| `optionDescription` | Second line |
| `check` | ✓ or checkbox |
| `empty` / `emptyText` | Empty state |

#### Types

```ts
interface SelectRenderOptionInfo<T> { option: SelectOption<T>; selected: boolean; disabled: boolean; theme: PickerTheme }
type SelectValueProps<T> =
  | { multiple?: false; value?: T | null; onChange?: (value: T, option: SelectOption<T>) => void }
  | { multiple: true; value?: T[]; onChange?: (value: T[], options: SelectOption<T>[]) => void; maxSelected?: number };
```

---

## React Native Select & Dropdown Picker

## SelectPicker

`SelectPicker` is a React Native form field that opens a bottom sheet with a searchable list: a dropdown / select that feels native on phones. Single or multiple selection, with groups, icons, descriptions, chips and a clear button.

```tsx
import { SelectPicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

const fruits = ['Apple', 'Banana', 'Cherry', 'Mango', 'Orange', 'Peach', 'Pear', 'Plum', 'Strawberry', 'Watermelon'].map((f) => ({
  label: f,
  value: f.toLowerCase(),
}));

export default function Example() {
  const [fruit, setFruit] = useState<string | null>(null);
  return <SelectPicker label="Favourite fruit" placeholder="Pick one" options={fruits} value={fruit} onChange={setFruit} />;
}
```

:::caution Always controlled
`SelectPicker` doesn't store the selection itself. Pass `value` and update it from `onChange`.
:::

### Try the props

<PropPlayground
  name="SelectPicker"
  component={SelectPicker}
  props={{
    label: 'Fruit',
    options: ['Apple', 'Banana', 'Cherry', 'Grape', 'Mango', 'Orange', 'Peach', 'Pear', 'Plum'].map((f) => ({ label: f, value: f })),
  }}
  value={(p) => (p.multiple ? ['Banana'] : 'Banana')}
  resetProp="onClear"
  code="label=&quot;Fruit&quot; options={fruits} value={value} onChange={setValue}"
  controls={[
    { prop: 'presentation', options: ['auto', 'dropdown', 'bottomSheet', 'modal'] },
    { prop: 'multiple', options: [false, true] },
    { prop: 'clearable', options: [false, true] },
    { prop: 'searchable', options: [true, false], default: null },
    { prop: 'chips', options: [true, false] },
    { prop: 'closeOnSelect', options: [true, false] },
    { prop: 'showCheckmarks', options: [true, false] },
    { prop: 'disabled', options: [false, true] },
  ]}
/>

### Options

```ts
interface SelectOption<T> {
  label: string;           // row text, and what search matches first
  value: T;                // any type; compared with isEqual (default Object.is)
  description?: string;    // second line, also searchable
  icon?: React.ReactNode;  // leading element: flag, avatar, icon
  group?: string;          // section header
  disabled?: boolean;
  keywords?: string[];     // extra search terms, e.g. other languages or synonyms
}
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const countries = [
  { label: 'Israel', value: 'IL', icon: <Text>🇮🇱</Text>, group: 'Middle East', keywords: ['ישראל'] },
  { label: 'Jordan', value: 'JO', icon: <Text>🇯🇴</Text>, group: 'Middle East' },
  { label: 'France', value: 'FR', icon: <Text>🇫🇷</Text>, group: 'Europe', description: 'République française' },
  { label: 'Germany', value: 'DE', icon: <Text>🇩🇪</Text>, group: 'Europe', keywords: ['deutschland'] },
  { label: 'Spain', value: 'ES', icon: <Text>🇪🇸</Text>, group: 'Europe', disabled: true, description: 'Not shipping yet' },
  { label: 'Japan', value: 'JP', icon: <Text>🇯🇵</Text>, group: 'Asia', keywords: ['nippon'] },
];

export default function Example() {
  const [country, setCountry] = useState<string | null>('FR');
  return <SelectPicker label="Ship to" options={countries} value={country} onChange={setCountry} searchable />;
}
```

Groups appear in the order their first option appears in `options`. Options without a `group` are listed together without a header.

### Multiple selection

`multiple` switches `value` to an array and `onChange` to `(values, options)`. The sheet gets checkboxes and a **Done** button, and the field shows removable **chips** (tap a chip to remove it). `maxSelected` caps the selection; once reached, the remaining options are disabled.

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

const skills = ['React', 'React Native', 'TypeScript', 'Expo', 'Node.js', 'GraphQL', 'Swift', 'Kotlin'].map((s) => ({ label: s, value: s }));

export default function Example() {
  const [picked, setPicked] = useState<string[]>(['React Native', 'TypeScript']);
  return (
    <SelectPicker
      multiple
      label="Skills (max 4)"
      placeholder="Add skills"
      options={skills}
      value={picked}
      onChange={setPicked}
      maxSelected={4}
      clearable
    />
  );
}
```

Set `chips={false}` to show a comma-separated list instead of chips.

### Search

As a **dropdown** (the default on the web), the user types right in the field to filter the options; `searchable={false}` keeps the field read-only. In a **sheet**, the search field appears automatically when there are **more than 8 options**; force it with `searchable` / `searchable={false}`. The default filter:

- matches `label`, `description` and `keywords`
- is case-insensitive and **accent-insensitive** (`creme` finds `Crème`), and ignores Hebrew niqqud
- splits the query on spaces and requires **every** word to match (`new yo` finds `New York`)

Provide `filterOption` for your own logic, for example matching only from the start of the label:

```tsx
<SelectPicker
  options={options}
  value={value}
  onChange={setValue}
  filterOption={(option, query) => option.label.toLowerCase().startsWith(query.toLowerCase())}
/>
```

The default is exported as `defaultFilter`, so you can extend it:

```tsx
import { defaultFilter } from '@elik56a/react-native-pickers';

filterOption={(o, q) => defaultFilter(o, q) || o.value === q.toUpperCase()}
```

### Clearing

`clearable` shows a × in the field when something is selected.

- In **multiple** mode, × calls `onChange([], [])` and then `onClear`.
- In **single** mode, × calls **only** `onClear`. Reset your state there:

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [v, setV] = useState<string | null>('b');
  return (
    <SelectPicker
      label="Priority"
      clearable
      onClear={() => setV(null)}
      options={[
        { label: 'Low', value: 'a' },
        { label: 'Medium', value: 'b' },
        { label: 'High', value: 'c', description: 'Pages on-call' },
      ]}
      value={v}
      onChange={setV}
    />
  );
}
```

### Closing behaviour

In single mode, the value changes as soon as an option is tapped and the sheet or dropdown closes a moment later, once the row's ripple has played (`closeOnSelect`, default `true`). With `closeOnSelect={false}` the sheet stays open and shows a **Done** button. Multiple mode always shows Done. `onOpen` and `onClose` fire when the sheet opens and closes.

### Hover and ripple

Rows tint while the pointer is over them and ripple from the touch point when picked; in single mode the list closes right after the ripple plays. The field tints on hover but doesn't ripple. Both colours come from the theme, so a brand tint is one prop:

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

const frameworks = ['Expo', 'React Native CLI', 'React Native Web', 'Next.js', 'Remix', 'Vite'].map((f) => ({ label: f, value: f }));

export default function Example() {
  const [framework, setFramework] = useState<string | null>(null);
  return (
    <SelectPicker
      label="Framework"
      placeholder="Choose a framework"
      options={frameworks}
      value={framework}
      onChange={setFramework}
      theme={{ colors: { hover: 'rgba(200,70,13,0.08)', ripple: 'rgba(200,70,13,0.24)' } }}
    />
  );
}
```

See [Theming → Hover and ripple](../guides/theming#hover-and-ripple) to change them everywhere or turn them off.

### Custom trigger

`renderTrigger` replaces the field. Call `open()` to show the sheet:

```tsx live
import { useState } from 'react';
import { Pressable, Text } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const sorts = [
  { label: 'Most relevant', value: 'relevance' },
  { label: 'Newest first', value: 'newest' },
  { label: 'Price: low to high', value: 'price_asc' },
  { label: 'Price: high to low', value: 'price_desc' },
];

export default function Example() {
  const [sort, setSort] = useState<string | null>('relevance');
  return (
    <SelectPicker
      options={sorts}
      value={sort}
      onChange={setSort}
      sheetTitle="Sort by"
      renderTrigger={({ open, selected }) => (
        <Pressable onPress={open} style={{ alignSelf: 'flex-start', paddingVertical: 8, paddingHorizontal: 14, borderRadius: 999, backgroundColor: '#EEF2FF' }}>
          <Text style={{ color: '#C8460D', fontWeight: '600' }}>↕ {selected[0]?.label ?? 'Sort'}</Text>
        </Pressable>
      )}
    />
  );
}
```

### Custom chevron

The field's chevron rotates when it opens and closes. `renderChevron` swaps the icon and keeps the rotation, so any icon works, an SVG included:

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const sizes = ['Small', 'Medium', 'Large'].map((s) => ({ label: s, value: s }));

export default function Example() {
  const [size, setSize] = useState<string | null>(null);
  return (
    <SelectPicker
      label="Size"
      options={sizes}
      value={size}
      onChange={setSize}
      renderChevron={({ theme }) => <Text style={{ color: theme.colors.primary, fontSize: 16 }}>⌄</Text>}
    />
  );
}
```

### Custom options

`renderOption` replaces each row's content (taps, selection background and accessibility are still handled). `renderGroupHeader` replaces section headers.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const people = [
  { label: 'Ada Lovelace', value: 'ada', description: 'Mathematician', color: '#F59E0B' },
  { label: 'Alan Turing', value: 'alan', description: 'Computer scientist', color: '#10B981' },
  { label: 'Grace Hopper', value: 'grace', description: 'Rear admiral', color: '#6366F1' },
];

export default function Example() {
  const [who, setWho] = useState<string | null>(null);
  return (
    <SelectPicker
      label="Assignee"
      options={people}
      value={who}
      onChange={setWho}
      renderOption={({ option, selected, theme }) => {
        const p = people.find((x) => x.value === option.value)!;
        return (
          <View style={{ flexDirection: 'row', alignItems: 'center', gap: 12, flex: 1 }}>
            <View style={{ width: 36, height: 36, borderRadius: 18, backgroundColor: p.color, alignItems: 'center', justifyContent: 'center' }}>
              <Text style={{ color: 'white', fontWeight: '700' }}>{p.label[0]}</Text>
            </View>
            <View style={{ flex: 1 }}>
              <Text style={{ color: theme.colors.text, fontWeight: selected ? '700' : '500' }}>{p.label}</Text>
              <Text style={{ color: theme.colors.textSecondary, fontSize: 12 }}>{p.description}</Text>
            </View>
            {selected && <Text style={{ color: theme.colors.primary }}>●</Text>}
          </View>
        );
      }}
    />
  );
}
```

### Presentation

`presentation` picks how the options open:

- `'auto'` (default): a dropdown on the web, a bottom sheet on native.
- `'bottomSheet'`: always a bottom sheet.
- `'modal'`: always a centered modal.
- `'dropdown'`: a popover under the field, as wide as the field. It flips above the field when there's more room there, and a tap outside closes it.

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [value, setValue] = useState(null);
  return (
    <SelectPicker
      label="Framework"
      value={value}
      onChange={setValue}
      options={['Expo', 'React Native CLI', 'Next.js', 'Vite'].map((label) => ({ label, value: label }))}
    />
  );
}
```

### Sheet options

Customise the sheet through `sheet`, which takes [`PickerSheet`](./picker-sheets#pickersheet) props such as `confirmLabel` and `sheetProps` (passed through to [`BottomSheet`](./bottom-sheet)):

```tsx
<SelectPicker
  options={options}
  value={value}
  onChange={setValue}
  sheetTitle="Choose a city"
  sheet={{ confirmLabel: 'Apply', sheetProps: { height: 0.7, enableSwipeToClose: false } }}
  listHeight={400}
  autoFocusSearch
/>
```

#### Expanding the sheet

Long lists open at their content height and can grow to full screen: drag the header up on iOS and Android, or scroll the wheel up over the sheet on the web. The list grows with the sheet. Set the expanded height through `sheet.sheetProps`:

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

const countries = [
  'Argentina', 'Australia', 'Austria', 'Belgium', 'Brazil', 'Canada', 'Chile', 'China', 'Denmark', 'Egypt',
  'Finland', 'France', 'Germany', 'Greece', 'India', 'Ireland', 'Israel', 'Italy', 'Japan', 'Mexico',
  'Netherlands', 'Norway', 'Poland', 'Portugal', 'Spain', 'Sweden', 'Switzerland', 'Turkey', 'United Kingdom', 'United States',
].map((c) => ({ label: c, value: c }));

export default function Example() {
  const [country, setCountry] = useState<string | null>(null);
  return (
    <SelectPicker
      label="Country"
      options={countries}
      value={country}
      onChange={setCountry}
      presentation="bottomSheet"
      sheet={{ sheetProps: { expandedHeight: 0.9, draggable: true } }}
    />
  );
}
```

`expandable: false` keeps the sheet at its content height; `draggable: false` turns off dragging on native. See [BottomSheet](./bottom-sheet#expanding-to-full-screen) for all the options.

### Props

#### Value

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `ReadonlyArray<SelectOption<T>>` | **required** | The options. |
| `multiple` | `boolean` | `false` | Multi-select mode. |
| `value` | `T \| null` · `T[]` | — | Selected value(s). |
| `onChange` | `(value: T, option: SelectOption<T>) => void` · `(values: T[], options: SelectOption<T>[]) => void` | — | Single · multiple. |
| `maxSelected` | `number` | — | Multiple only: maximum selected options. |
| `isEqual` | `(a: T, b: T) => boolean` | `Object.is` | Value equality. |

#### Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Label above the field; also the default sheet title. |
| `placeholder` | `string` | `'Select…'` | Shown when nothing is selected. |
| `disabled` | `boolean` | `false` | Disable the field. |
| `clearable` | `boolean` | `false` | Show a × button when something is selected. |
| `onClear` | `() => void` | — | Called by ×. In single mode, reset `value` here. |
| `chips` | `boolean` | `true` | Multiple: show selections as removable chips. |
| `renderChevron` | `(info: { open, theme }) => ReactNode` | — | Custom chevron icon (an SVG, an icon font…). It still rotates on open and close. |
| `renderTrigger` | `(info: { open, selected, disabled }) => ReactNode` | — | Replace the field entirely. |
| `style` | `StyleProp<ViewStyle>` | — | Wrapper style (label + field). |

#### Sheet & list

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `presentation` | `'auto' \| 'bottomSheet' \| 'modal' \| 'dropdown'` | `'auto'` | How the options open. `auto`: dropdown on the web, bottom sheet on native. |
| `sheetTitle` | `string` | `label` | Sheet header title. |
| `closeOnSelect` | `boolean` | `true` | Single: close on tap. `false` shows a Done button. |
| `sheet` | `Partial<SheetChromeProps>` | — | `confirmLabel`, `cancelLabel`, `showCancel`, `title`, `sheetProps`. |
| `onOpen` / `onClose` | `() => void` | — | Sheet open / close. |
| `searchable` | `boolean` | dropdown: `true` · sheet: `options.length > 8` | Dropdown: type in the field to filter. Sheet: show the search field. |
| `searchPlaceholder` | `string` | `'Search'` | Search hint. |
| `filterOption` | `(option, query) => boolean` | `defaultFilter` | Custom search. |
| `emptyText` | `string` | `'No results'` | Shown when nothing matches. |
| `showCheckmarks` | `boolean` | `true` | Check marks / checkboxes on rows. |
| `renderOption` | `(info: { option, selected, disabled, theme }) => ReactNode` | — | Custom row content. |
| `renderGroupHeader` | `(group: string, theme) => ReactNode` | — | Custom section header. |
| `listHeight` | `number` | grows with content | Fixed list height. |
| `autoFocusSearch` | `boolean` | `false` | Focus search when the sheet opens. |
| `styles` | `SlotStyles<SelectSlot \| SelectTriggerSlot>` | — | Slots for both the field and the list. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID on the list. |

#### Slots

**Field** (`SelectTriggerSlot`):

| Slot | Element |
| --- | --- |
| `label` | Label text above the field |
| `trigger` | The field box |
| `triggerText` | Selected label(s) |
| `placeholder` | Placeholder text |
| `chip` / `chipText` | Multi-select chips |
| `chevron` | The drawn chevron (a bordered `View`: `borderColor` sets its color, `width` / `height` its size) |
| `clear` | × button text |

**List**: see [SelectList slots](./select-list#slots).

### Accessibility

The field is a button labelled with `label` (or the placeholder), with the current selection as its hint and an `expanded` state. Options are `button`s (single) or `checkbox`es (multiple) with `selected` / `checked` / `disabled` states, and chips announce `Remove {label}`.

### Related

- [SelectList](./select-list): the list without the field and sheet
- [Picker fields](./picker-fields): the same field for dates, times, wheels and emoji
- [Country select recipe](../recipes/country-select)
- [Tag picker recipe](../recipes/tags)

---

## React Native Time Picker

## TimePicker

`TimePicker` is a React Native time picker made of hour, minute (and optionally second and AM/PM) wheels. The 12h or 24h clock and the AM/PM labels come from the locale automatically.

```tsx
import { TimePicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [time, setTime] = useState(new Date());
  return (
    <>
      <TimePicker value={time} onChange={setTime} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>{time.toLocaleTimeString()}</Text>
    </>
  );
}
```

### Try the props

### The value is a `Date`

`value` and `onChange` use a JavaScript `Date`. Only the hours, minutes and seconds are changed; **the date part is preserved**, so you can pass a full appointment `Date` and get the same day back with a new time. When `showSeconds` is off, seconds and milliseconds are set to `0`.

### 12h / 24h

`format` is `'auto'` by default and is resolved from `locale` (or the device locale). Force it with `'12h'` or `'24h'`.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 14, 45));
  return (
    <View style={{ gap: 16 }}>
      <Text style={{ fontWeight: '600' }}>en-US (12h)</Text>
      <TimePicker value={time} onChange={setTime} locale="en-US" />
      <Text style={{ fontWeight: '600' }}>de-DE (24h)</Text>
      <TimePicker value={time} onChange={setTime} locale="de-DE" />
    </View>
  );
}
```

AM/PM labels come from the locale too (`AM`/`PM`, `a.m.`/`p.m.`, `午前`/`午後`…). Override them with `dayPeriodLabels`, and use `dayPeriodFirst` for languages that put the period before the hour (Chinese, Korean, Japanese):

```tsx live
import { useState } from 'react';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 9, 30));
  return <TimePicker value={time} onChange={setTime} format="12h" locale="ko-KR" dayPeriodFirst />;
}
```

Hours are zero-padded in 24h mode (`09`) and not in 12h mode (`9`); change that with `padHours`.

### Intervals

`minuteInterval` shows only every n-th minute (5, 10, 15, 30…). `showSeconds` adds a seconds wheel with its own `secondInterval`. A value whose minutes don't fall on the interval is shown rounded **down** (10:07 with a 5-minute step shows 10:05). `TimePickerSheet` and `DateTimePickerSheet` confirm the time as shown, so pressing **Done** without scrolling returns 10:05.

```tsx live
import { useState } from 'react';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 0, 2, 30));
  return <TimePicker value={time} onChange={setTime} format="24h" showSeconds secondInterval={5} minuteInterval={1} />;
}
```

### Min and max time

`minTime` and `maxTime` limit the selectable **time of day** (their date part is ignored). Hours and minutes outside the range are disabled, and a combination that ends up out of range (for example, changing the hour while sitting on a late minute) is clamped into the range when committed.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { TimePicker } from '@elik56a/react-native-pickers';

const at = (h: number, m = 0) => new Date(2026, 0, 1, h, m);

export default function Example() {
  const [time, setTime] = useState(at(12));
  return (
    <>
      <Text style={{ textAlign: 'center', marginBottom: 8, color: '#6E685E' }}>Opening hours: 09:00 – 17:30</Text>
      <TimePicker value={time} onChange={setTime} minTime={at(9)} maxTime={at(17, 30)} minuteInterval={15} format="24h" />
    </>
  );
}
```

### Looping

Hour, minute and second wheels loop by default. Set `loop={false}` for wheels that stop at the ends. The AM/PM wheel never loops.

### Uncontrolled

```tsx
<TimePicker defaultValue={new Date()} onChange={(d) => save(d)} />
```

Without `value` or `defaultValue`, the picker starts at the current time.

### In a sheet

```tsx
import { TimePickerSheet } from '@elik56a/react-native-pickers';

<TimePickerSheet visible={open} onClose={() => setOpen(false)} title="Alarm" value={time} onConfirm={setTime} minuteInterval={5} />
```

→ [TimePickerSheet](./picker-sheets#timepickersheet)

### In a form field

`TimePickerField` is a field that opens the sheet and shows the confirmed time (`9:30 AM` or `09:30`, from `format` and `locale`):

```tsx
import { TimePickerField } from '@elik56a/react-native-pickers';

<TimePickerField label="Alarm" placeholder="Set a time" value={time} onConfirm={setTime} minuteInterval={5} />
```

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected time (controlled). The date part is preserved. |
| `defaultValue` | `Date` | now | Initial time when uncontrolled. |
| `onChange` | `(date: Date) => void` | — | Fires when any wheel settles. Receives a **new** `Date`. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick while scrolling (haptics). |
| `format` | `'12h' \| '24h' \| 'auto'` | `'auto'` | Clock format; `'auto'` reads it from `locale`. |
| `locale` | `string` | device | BCP 47 locale, e.g. `'en-US'`, `'he-IL'`. |
| `minuteInterval` | `number` | `1` | Minute step: 1, 5, 10, 15, 30… |
| `showSeconds` | `boolean` | `false` | Add a seconds wheel. |
| `secondInterval` | `number` | `1` | Second step. |
| `minTime` | `Date` | — | Earliest selectable time of day. |
| `maxTime` | `Date` | — | Latest selectable time of day. |
| `loop` | `boolean` | `true` | Loop the hour / minute / second wheels. |
| `padHours` | `boolean` | `true` for 24h, `false` for 12h | Zero-pad the hour labels. |
| `dayPeriodLabels` | `[string, string]` | from locale | `[am, pm]` labels. |
| `dayPeriodFirst` | `boolean` | `false` | Put the AM/PM wheel before the hours. |
| `separator` | `ReactNode` | `':'` | Shown between hours, minutes and seconds (not next to AM/PM). |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` | Visible rows. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `testID` | `string` | — | Test ID. |

### Related

- [Alarm recipe](../recipes/alarm-time)
- [TimePickerField](./picker-fields): the picker behind a form field
- [Duration picker](../recipes/duration): for lengths of time rather than a time of day, use `MultiWheelPicker`

---

## React Native Wheel Picker

## WheelPicker

`WheelPicker` is an iOS-style scrolling wheel for React Native. Rows curve away on a 3D cylinder (or stay flat), snap into the selection band, and can loop forever. Works the same on iOS, Android and web.

```tsx
import { WheelPicker } from '@elik56a/react-native-pickers';
```

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [size, setSize] = useState('M');
  return <WheelPicker items={['XS', 'S', 'M', 'L', 'XL', 'XXL']} value={size} onChange={setSize} />;
}
```

### Try the props

### Items

`items` accepts **primitives** (strings or numbers) or **objects**. Mix freely, but objects are the way to add labels, disabled rows or non-primitive values.

```ts
type WheelItem<T> = {
  label: string;      // text shown on the row
  value: T;           // what onChange gives you
  disabled?: boolean; // rendered dimmed; the wheel never settles on it
  key?: string;
};

items: ReadonlyArray<WheelItem<T> | T>   // T must be string | number for the shorthand
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { WheelPicker } from '@elik56a/react-native-pickers';

const plans = [
  { label: 'Free', value: { id: 'free', price: 0 } },
  { label: 'Pro — $9', value: { id: 'pro', price: 9 } },
  { label: 'Team — $29', value: { id: 'team', price: 29 } },
  { label: 'Enterprise (contact us)', value: { id: 'ent', price: -1 }, disabled: true },
];

export default function Example() {
  const [plan, setPlan] = useState(plans[1].value);
  return (
    <>
      <WheelPicker
        items={plans}
        value={plan}
        onChange={setPlan}
        isEqual={(a, b) => a.id === b.id}
      />
      <Text style={{ textAlign: 'center', marginTop: 8, color: '#6E685E' }}>Selected: {plan.id}</Text>
    </>
  );
}
```

:::info Object values need `isEqual`
Selection is matched with `Object.is` by default. If your values are objects that may be re-created between renders, pass `isEqual` so the wheel can find the selected row.
:::

### Infinite loop

`loop` makes the wheel wrap around: scroll past the last item to reach the first. Internally the list is repeated and silently re-centred when it settles, so the user can never hit an end.

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

const minutes = Array.from({ length: 60 }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i }));

export default function Example() {
  const [minute, setMinute] = useState(30);
  return <WheelPicker items={minutes} value={minute} onChange={setMinute} loop />;
}
```

### Disabled items

Disabled rows are shown dimmed and are never selected. If the user lets go on one, the wheel springs to the nearest enabled row. If the initial `value` points at a disabled row, the nearest enabled row is shown.

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

const slots = ['09:00', '09:30', '10:00', '10:30', '11:00', '11:30', '12:00'].map((t, i) => ({
  label: i % 3 === 1 ? `${t} · booked` : t,
  value: t,
  disabled: i % 3 === 1,
}));

export default function Example() {
  const [slot, setSlot] = useState('10:00');
  return <WheelPicker items={slots} value={slot} onChange={setSlot} />;
}
```

### Flat variant and the 3D look

`variant="flat"` turns off the cylinder; rows just fade and scale slightly. For the 3D wheel, `rotation` sets how sharply it curves (degrees between rows) and `fadeTo` sets the opacity of the outermost rows.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { WheelPicker } from '@elik56a/react-native-pickers';

const items = Array.from({ length: 20 }, (_, i) => i + 1);

export default function Example() {
  const [a, setA] = useState(5);
  const [b, setB] = useState(5);
  const [c, setC] = useState(5);
  return (
    <View style={{ flexDirection: 'row', gap: 8 }}>
      <WheelPicker style={{ flex: 1 }} items={items} value={a} onChange={setA} />
      <WheelPicker style={{ flex: 1 }} items={items} value={b} onChange={setB} rotation={32} fadeTo={0.1} />
      <WheelPicker style={{ flex: 1 }} items={items} value={c} onChange={setC} variant="flat" />
    </View>
  );
}
```

### Size: `itemHeight` and `visibleItems`

The wheel is exactly `itemHeight × visibleItems` tall. `visibleItems` should be odd so one row sits in the middle; an even number is rounded up.

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [v, setV] = useState('Medium');
  return (
    <WheelPicker
      items={['Tiny', 'Small', 'Medium', 'Large', 'Huge']}
      value={v}
      onChange={setV}
      itemHeight={52}
      visibleItems={3}
      styles={{ itemText: { fontSize: 24 } }}
    />
  );
}
```

### Tap-to-type

With `keyboardInput` (on by default), tapping the **selected** row opens the keyboard. As the user types, the wheel jumps to the first matching label, and the value is committed when the wheel settles, exactly as if they had scrolled.

- **Numeric wheels** (every label is digits) match by number, so typing `5` finds `05`, and the numeric keyboard is shown.
- **Text wheels** match by case-insensitive prefix (`ju` → `June`).
- Typing continues while more characters could still narrow the match, then the keyboard closes.

Tap the selected row below, then type:

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

const years = Array.from({ length: 101 }, (_, i) => 1930 + i);

export default function Example() {
  const [year, setYear] = useState(1990);
  return <WheelPicker items={years} value={year} onChange={setYear} />;
}
```

Set `keyboardInput={false}` to disable it. Tapping a non-selected row always scrolls to that row.

### Custom rows

`renderItem` replaces the row content. You get the item, its index, whether it's selected and the active theme.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { WheelPicker } from '@elik56a/react-native-pickers';

const currencies = [
  { label: 'USD', value: 'USD', flag: '🇺🇸', name: 'US Dollar' },
  { label: 'EUR', value: 'EUR', flag: '🇪🇺', name: 'Euro' },
  { label: 'GBP', value: 'GBP', flag: '🇬🇧', name: 'Pound' },
  { label: 'JPY', value: 'JPY', flag: '🇯🇵', name: 'Yen' },
  { label: 'ILS', value: 'ILS', flag: '🇮🇱', name: 'Shekel' },
];

export default function Example() {
  const [cur, setCur] = useState('EUR');
  return (
    <WheelPicker
      items={currencies}
      value={cur}
      onChange={setCur}
      itemHeight={48}
      renderItem={({ item, selected, theme }) => {
        const c = currencies.find((x) => x.value === item.value)!;
        return (
          <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 10 }}>
            <Text style={{ fontSize: 22 }}>{c.flag}</Text>
            <Text style={{ fontSize: 18, fontWeight: selected ? '700' : '400', color: selected ? theme.colors.text : theme.colors.textSecondary }}>
              {c.label}
            </Text>
            {selected && <Text style={{ color: theme.colors.textSecondary }}>{c.name}</Text>}
          </View>
        );
      }}
    />
  );
}
```

`renderIndicator` replaces the selection band (the grey pill behind the selected row), and `showIndicator={false}` removes it:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { WheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [v, setV] = useState(3);
  return (
    <WheelPicker
      items={[1, 2, 3, 4, 5, 6, 7]}
      value={v}
      onChange={setV}
      renderIndicator={(theme) => (
        <View style={{ height: 40, borderTopWidth: 2, borderBottomWidth: 2, borderColor: theme.colors.primary, marginHorizontal: 24 }} />
      )}
    />
  );
}
```

### Haptics

`onValueChanging` fires on every row crossing, the perfect hook for a selection tick. The library imposes no haptics dependency; use whichever you like:

```tsx
import * as Haptics from 'expo-haptics';

<WheelPicker items={items} value={value} onChange={setValue} onValueChanging={() => Haptics.selectionAsync()} />
```

→ [Haptics guide](../guides/haptics)

### In a form field

`WheelPickerField` opens the wheel in a sheet from a field, and shows the confirmed item's `label`:

```tsx live
import { useState } from 'react';
import { WheelPickerField } from '@elik56a/react-native-pickers';

const sizes = ['XS', 'S', 'M', 'L', 'XL'];

export default function Example() {
  const [size, setSize] = useState<string | undefined>();
  return <WheelPickerField label="Size" placeholder="Choose a size" items={sizes} value={size} onConfirm={setSize} />;
}
```

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ReadonlyArray<WheelItem<T> \| T>` | **required** | Rows. Primitives (`string \| number`) or `{ label, value, disabled?, key? }`. |
| `value` | `T` | — | Selected value (controlled). Changing it scrolls the wheel without firing `onChange`. |
| `defaultValue` | `T` | first enabled item | Initial value when uncontrolled. |
| `onChange` | `(value: T, index: number) => void` | — | Fires once the wheel settles on a **new** value. `index` is the position in `items`. |
| `onValueChanging` | `(value: T, index: number) => void` | — | Fires on every row crossing while scrolling (skips disabled rows). Use for haptics. |
| `itemHeight` | `number` | `40` | Row height in px. |
| `visibleItems` | `number` | `5` | Visible rows. Odd numbers; even values are rounded up. |
| `loop` | `boolean` | `false` | Infinite wheel that wraps around. |
| `keyboardInput` | `boolean` | `true` | Tap the selected row to type a value. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Cylinder or flat list. |
| `rotation` | `number` | `20` | Degrees between rows on the 3D cylinder. Higher = sharper curve. |
| `fadeTo` | `number` | `0.3` | Opacity of the farthest visible rows (0–1). |
| `renderItem` | `(info: WheelRenderItemInfo<T>) => ReactNode` | — | Custom row content. `info = { item, index, selected, theme }`. |
| `showIndicator` | `boolean` | `true` | Show the selection band. |
| `renderIndicator` | `(theme: PickerTheme) => ReactNode` | — | Custom selection band, vertically centred. |
| `textAlign` | `TextStyle['textAlign']` | `'center'` | Alignment of the default row label. |
| `disabled` | `boolean` | `false` | Disable scrolling and taps. |
| `isEqual` | `(a: T, b: T) => boolean` | `Object.is` | Equality used to find the selected row. |
| `style` | `StyleProp<ViewStyle>` | — | Outer container style (e.g. `flex`, `width`). |
| `styles` | `SlotStyles<WheelPickerSlot>` | — | Per-slot styles; see below. |
| `theme` | `DeepPartial<PickerTheme>` | — | Component-level theme override. |
| `accessibilityLabel` | `string` | — | Label announced by screen readers. |
| `testID` | `string` | — | Test ID on the container. |

#### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view (fixed height `itemHeight × visibleItems`) |
| `item` | Each row's animated wrapper |
| `itemText` | Every row label |
| `selectedItemText` | Label of the row in the band (merged after `itemText`) |
| `disabledItemText` | Labels of disabled rows |
| `indicator` | The selection band |

#### Types

```ts
interface WheelItem<T> { label: string; value: T; disabled?: boolean; key?: string }
type WheelItemInput<T> = WheelItem<T> | (T extends string | number ? T : never);
type WheelPickerSlot = 'container' | 'item' | 'itemText' | 'selectedItemText' | 'disabledItemText' | 'indicator';
interface WheelRenderItemInfo<T> { item: WheelItem<T>; index: number; selected: boolean; theme: PickerTheme }
```

### Behaviour notes

- `onChange` fires only when the settled value **differs** from the last committed one. Scrolling away and back doesn't fire it.
- Scrolling with momentum fires `onChange` once, after momentum ends.
- A wheel with `loop` and very few items repeats the list enough times (at least 7 copies, about 240 rows) for smooth flinging.
- Rows are memoized; while scrolling only the two rows whose selected state changes re-render.

### Accessibility

The wheel is a single `adjustable` element. VoiceOver and TalkBack users swipe up / down to move one row (the `increment` / `decrement` actions), and the current label is announced as the value. Pass `accessibilityLabel` to name it ("Size").

### Related

- [MultiWheelPicker](./multi-wheel-picker): several wheels in one band
- [WheelPickerSheet](./picker-sheets#wheelpickersheet): the wheel in a bottom sheet
- [WheelPickerField](./picker-fields): the wheel behind a form field

---

## Date utilities

The helpers the pickers use internally, exported for your own code. All of them:

- work in **local time** (no UTC surprises)
- **never mutate** their inputs
- fall back to English names if `Intl` is missing or a locale is invalid

```ts
import { toDateKey, addDays, isSameDay, formatDate } from '@elik56a/react-native-pickers';
```

### Arithmetic

#### `startOfDay`

```ts
startOfDay(d: Date): Date
```
Same day at 00:00:00.000.

#### `startOfMonth`

```ts
startOfMonth(d: Date): Date
```
First day of the month at 00:00.

#### `daysInMonth`

```ts
daysInMonth(year: number, month: number): number   // month is 0-based
daysInMonth(2028, 1) // 29
```

#### `addDays`

```ts
addDays(d: Date, days: number): Date
```
Adds calendar days (negative to subtract), keeping hours and minutes (seconds and milliseconds are reset). DST-safe, because it works on date parts rather than milliseconds.

#### `addMonths`

```ts
addMonths(d: Date, months: number): Date
addMonths(new Date(2026, 0, 31), 1) // Feb 28 2026 (clamped)
```
Clamps the day to the target month's length and keeps the time.

#### `clampDate`

```ts
clampDate(d: Date, min?: Date | null, max?: Date | null): Date
```
Returns a copy of `min` / `max` when `d` is outside them (by exact time), else `d`.

### Comparison

#### `isSameDay`

```ts
isSameDay(a?: Date | null, b?: Date | null): boolean
```
Same calendar day; `false` if either is null.

#### `isSameMonth`

```ts
isSameMonth(a: Date, b: Date): boolean
```

#### `compareDay`

```ts
compareDay(a: Date, b: Date): number   // < 0, 0, > 0
```
Compares calendar days, ignoring time. Use it as a sort comparator: `dates.sort(compareDay)`.

#### `isBetweenDays`

```ts
isBetweenDays(d: Date, start?: Date | null, end?: Date | null): boolean
```
`true` when `d` is **strictly** between `start` and `end` (exclusive), by day.

#### `isOutOfRange`

```ts
isOutOfRange(d: Date, min?: Date | null, max?: Date | null): boolean
```
`true` when `d`'s day is before `min`'s day or after `max`'s day.

### Keys and grids

#### `toDateKey`

```ts
toDateKey(d: Date): string   // 'YYYY-MM-DD' in local time
```
The key format of `markedDates`. Use it instead of `toISOString().slice(0, 10)`, which converts to UTC and can be off by a day.

#### `buildMonthGrid`

```ts
buildMonthGrid(year: number, month: number, firstDayOfWeek = 0, fixedWeeks = true): Date[][]
```
Weeks × 7 days for a month view, including leading and trailing days of neighbouring months. 6 weeks when `fixedWeeks`, else only as many as needed. Handy for custom calendars and heatmaps.

### Locale

#### `getMonthNames`

```ts
getMonthNames(locale?: string, width: 'long' | 'short' = 'long'): string[]   // 12 names
```

#### `getWeekdayNames`

```ts
getWeekdayNames(locale?: string, width: 'long' | 'short' | 'narrow' = 'short'): string[]
```
7 names indexed by JS day: **0 = Sunday**.

#### `formatMonthYear`

```ts
formatMonthYear(d: Date, locale?: string): string   // 'October 2026'
```

#### `formatDate`

```ts
formatDate(d: Date, locale?: string, opts: Intl.DateTimeFormatOptions = { dateStyle: 'medium' }): string
formatDate(new Date(2026, 9, 14))                          // 'Oct 14, 2026'
formatDate(new Date(2026, 9, 14), 'de-DE', { dateStyle: 'full' }) // 'Mittwoch, 14. Oktober 2026'
```
Cached `Intl.DateTimeFormat`, falling back to `YYYY-MM-DD`.

#### `uses12HourClock`

```ts
uses12HourClock(locale?: string): boolean
```
`true` when the locale formats hours with AM/PM.

#### `getFirstDayOfWeek`

```ts
getFirstDayOfWeek(locale?: string): number   // 0 = Sunday … 6 = Saturday
```
From `Intl.Locale` week info when the runtime supports it; otherwise `0`. Returns `0` when no `locale` is given.

#### `getDayPeriods`

```ts
getDayPeriods(locale?: string): [string, string]   // ['AM', 'PM'], ['午前', '午後'], …
```

---

## Emoji utilities

The data and search behind `EmojiPicker`, for your own UIs.

```ts
import { getAllEmojis, searchEmojis, findEmoji, withSkinTone } from '@elik56a/react-native-pickers';
```

### `getAllEmojis`

```ts
getAllEmojis(): Emoji[]
```
All 1,906 emojis in display order. Parsed on the first call, then cached.

```ts
interface Emoji {
  emoji: string;
  name: string;
  keywords: string[];
  category: EmojiCategory;
  version: number;   // Emoji version, e.g. 0.6, 11, 15.1
  skins?: string[];  // 5 variants, light → dark
}
```

### `searchEmojis`

```ts
searchEmojis(query: string, list: Emoji[] = getAllEmojis()): Emoji[]
```

Every word of the query must match. Results are ranked by:

1. name starts with the word (3 points)
2. a word of the name starts with it (2)
3. a keyword starts with it (1)
4. the name contains it (0.5)

Returns `[]` for an empty query.

```tsx live
import { useState } from 'react';
import { Text, TextInput, View } from 'react-native';
import { searchEmojis } from '@elik56a/react-native-pickers';

export default function Example() {
  const [q, setQ] = useState('heart');
  const results = searchEmojis(q).slice(0, 24);
  return (
    <View style={{ gap: 12 }}>
      <TextInput value={q} onChangeText={setQ} placeholder=":shortcode" style={{ borderWidth: 1, borderColor: '#E8E4DC', borderRadius: 10, padding: 10 }} />
      <Text style={{ fontSize: 28, lineHeight: 40 }}>{results.map((e) => e.emoji).join(' ')}</Text>
    </View>
  );
}
```

### `findEmoji`

```ts
findEmoji(char: string): Emoji | undefined
```
Looks up an emoji by character. Matches skin-tone variants too (`findEmoji('👍🏽')` returns 👍's data) and ignores the U+FE0F variation selector.

### `withSkinTone`

```ts
withSkinTone(e: Emoji, tone: SkinTone): string
withSkinTone(findEmoji('👋')!, 3) // '👋🏽'
```
Returns the variant for tone 1–5, or the base emoji for tone 0 or emojis without skins.

### Constants

```ts
EMOJI_CATEGORIES: EmojiCategory[]
// ['smileys', 'people', 'animals', 'food', 'travel', 'activities', 'objects', 'symbols', 'flags']

DEFAULT_CATEGORY_LABELS: Record<EmojiCategory | 'recent' | 'search', string>
// { recent: 'Recently used', search: 'Search results', smileys: 'Smileys & Emotion', … }

DEFAULT_CATEGORY_ICONS: Record<EmojiCategory | 'recent', string>
// { recent: '🕘', smileys: '😀', people: '👋', animals: '🐻', food: '🍔', travel: '✈️', activities: '⚽', objects: '💡', symbols: '❤️', flags: '🏳️' }
```

### Example: quick reactions

```tsx
const QUICK = ['👍', '❤️', '😂', '😮', '😢', '🙏'];
const [tone] = useState<SkinTone>(2);

<View style={{ flexDirection: 'row' }}>
  {QUICK.map((ch) => {
    const e = findEmoji(ch)!;
    const toned = withSkinTone(e, tone);
    return <Pressable key={ch} onPress={() => react(toned)}><Text style={{ fontSize: 28 }}>{toned}</Text></Pressable>;
  })}
</View>
```

---

## API reference

Every export from `@elik56a/react-native-pickers`, grouped. Each name links to its full documentation.

### Components

| Export | Description |
| --- | --- |
| [`WheelPicker<T>`](../components/wheel-picker) | Single scrolling wheel |
| [`MultiWheelPicker`](../components/multi-wheel-picker) | Several wheels in one band |
| [`TimePicker`](../components/time-picker) | Hour / minute / second / AM-PM wheels |
| [`DatePicker`](../components/date-picker) | Calendar (`display="calendar"`) or wheel (`display="wheel"`) |
| [`Calendar`](../components/date-picker) | Month calendar: single / range / multiple / ranges |
| [`DateWheelPicker`](../components/date-wheel-picker) | Day / month / year wheels |
| [`DateTimePicker`](../components/date-time-picker) | Day + time wheels (`display="wheel"`) or calendar + time (`display="calendar"`) |
| [`SelectPicker<T>`](../components/select-picker) | Field + searchable sheet |
| [`SelectList<T>`](../components/select-list) | Inline searchable list |
| [`EmojiPicker`](../components/emoji-picker) | Emoji keyboard |
| [`BottomSheet`](../components/bottom-sheet) | Animated sheet |

### Sheets

| Export | Description |
| --- | --- |
| [`PickerSheet`](../components/picker-sheets#pickersheet) | BottomSheet with Cancel / Done |
| [`DatePickerSheet`](../components/picker-sheets#datepickersheet) | Calendar or date wheel in a sheet |
| [`TimePickerSheet`](../components/picker-sheets#timepickersheet) | TimePicker in a sheet |
| [`DateTimePickerSheet`](../components/date-time-picker#in-a-sheet) | DateTimePicker in a sheet |
| [`WheelPickerSheet<T>`](../components/picker-sheets#wheelpickersheet) | WheelPicker in a sheet |
| [`EmojiPickerSheet`](../components/picker-sheets#emojipickersheet) | EmojiPicker in a sheet |
| [`useDraft(value, visible)`](../components/picker-sheets#usedraft) | Draft state that resets on open |

### Fields

| Export | Description |
| --- | --- |
| [`PickerField`](../components/picker-fields#your-own-sheet-pickerfield) | Labelled field that opens the sheet its child renders |
| [`DatePickerField`](../components/picker-fields) | Field + DatePickerSheet; shows the date, range or dates |
| [`TimePickerField`](../components/picker-fields) | Field + TimePickerSheet; shows the time |
| [`DateTimePickerField`](../components/picker-fields) | Field + DateTimePickerSheet; shows the date and time |
| [`WheelPickerField<T>`](../components/picker-fields) | Field + WheelPickerSheet; shows the item's label |
| [`EmojiPickerField`](../components/picker-fields) | Field + EmojiPickerSheet; shows `value` |

### Theme

| Export | Description |
| --- | --- |
| [`PickersProvider`](../guides/theming#pickersprovider) | App-wide theme and colour scheme |
| [`usePickerTheme(override?)`](./theme#usepickertheme) | Resolved active theme |
| [`createTheme(overrides, base?)`](./theme#createtheme) | Full theme from overrides |
| [`mergeTheme(base, override?)`](./theme#mergetheme) | Deep merge |
| [`lightTheme`](./theme#lighttheme--darktheme) / [`darkTheme`](./theme#lighttheme--darktheme) | Built-in themes |
| [`textStyle(theme, size, weight?)`](./theme#textstyle) | Text style from tokens |

### Date utilities

[`startOfDay`](./date-utils#startofday) · [`startOfMonth`](./date-utils#startofmonth) · [`daysInMonth`](./date-utils#daysinmonth) · [`addDays`](./date-utils#adddays) · [`addMonths`](./date-utils#addmonths) · [`isSameDay`](./date-utils#issameday) · [`isSameMonth`](./date-utils#issamemonth) · [`compareDay`](./date-utils#compareday) · [`isBetweenDays`](./date-utils#isbetweendays) · [`isOutOfRange`](./date-utils#isoutofrange) · [`clampDate`](./date-utils#clampdate) · [`toDateKey`](./date-utils#todatekey) · [`buildMonthGrid`](./date-utils#buildmonthgrid) · [`getMonthNames`](./date-utils#getmonthnames) · [`getWeekdayNames`](./date-utils#getweekdaynames) · [`formatMonthYear`](./date-utils#formatmonthyear) · [`formatDate`](./date-utils#formatdate) · [`uses12HourClock`](./date-utils#uses12hourclock) · [`getFirstDayOfWeek`](./date-utils#getfirstdayofweek) · [`getDayPeriods`](./date-utils#getdayperiods)

`CALENDAR_MODE`: the calendar selection modes as constants (`single`, `range`, `multiple`, `ranges`), e.g. `mode={CALENDAR_MODE.ranges}`.

### Emoji utilities

[`getAllEmojis`](./emoji-utils#getallemojis) · [`searchEmojis`](./emoji-utils#searchemojis) · [`findEmoji`](./emoji-utils#findemoji) · [`withSkinTone`](./emoji-utils#withskintone) · [`EMOJI_CATEGORIES`](./emoji-utils#constants) · [`DEFAULT_CATEGORY_LABELS`](./emoji-utils#constants) · [`DEFAULT_CATEGORY_ICONS`](./emoji-utils#constants)

### Select utilities

| Export | Description |
| --- | --- |
| [`defaultFilter(option, query)`](../components/select-picker#search) | The default search: case-, accent- and niqqud-insensitive; every word must match label, description or keywords |

### Types

See [TypeScript](../guides/typescript#exported-types) for the full list. The most used:

```ts
interface DateRange { start: Date | null; end: Date | null }

interface MarkedDate { dots?: string[]; disabled?: boolean; label?: string; textColor?: string }

interface SelectOption<T> {
  label: string; value: T; description?: string; disabled?: boolean;
  icon?: React.ReactNode; group?: string; keywords?: string[];
}

interface WheelItem<T> { label: string; value: T; disabled?: boolean; key?: string }

type SkinTone = 0 | 1 | 2 | 3 | 4 | 5;

/** Every sheet's `presentation`. */
type SheetPresentation = 'auto' | 'bottomSheet' | 'modal';

/** SelectPicker's `presentation`; its `auto` is a dropdown on the web. */
type SelectPresentation = SheetPresentation | 'dropdown';

/** The field slots every `*PickerField` and `PickerField` takes in `styles`. */
type PickerFieldSlot = 'label' | 'trigger' | 'triggerText' | 'placeholder' | 'chevron' | 'clear';

type SlotStyles<K extends string> = Partial<Record<K, StyleProp<TextStyle>>>;

interface ThemableProps { theme?: DeepPartial<PickerTheme> }
```

### Default strings

| Where | Prop | Default |
| --- | --- | --- |
| Sheets | `confirmLabel` / `cancelLabel` | `Done` / `Cancel` |
| SelectPicker, fields | `placeholder` | `Select…` |
| SelectList | `searchPlaceholder` / `emptyText` | `Search` / `No results` |
| EmojiPicker | `searchPlaceholder` / `emptyText` | `Search emoji` / `No emoji found` |
| TimePicker | `dayPeriodLabels` | from locale (`AM` / `PM`) |

### Default values at a glance

| Prop | Default | Components |
| --- | --- | --- |
| `itemHeight` | `40` | wheels |
| `visibleItems` | `5` | wheels |
| `variant` | `'3d'` | wheels |
| `rotation` / `fadeTo` | `20` / `0.3` | WheelPicker |
| `loop` | `false` WheelPicker · `true` TimePicker, DateWheelPicker | wheels |
| `keyboardInput` | `true` | WheelPicker |
| `minuteInterval` / `secondInterval` | `1` | TimePicker |
| `format` | `'auto'` | TimePicker |
| `dayHeight` | `44` | Calendar |
| `fixedWeeks` / `showOutsideDays` | `true` | Calendar |
| `enableSwipe` / `enableQuickJump` | `true` | Calendar |
| `weekdayFormat` | `'short'` | Calendar |
| `monthFormat` | `'long'` | DateWheelPicker |
| `searchable` | `options.length > 8` · `true` emoji | Select, Emoji |
| `closeOnSelect` | `true` | SelectPicker, EmojiPickerSheet |
| `chips` | `true` | SelectPicker |
| `clearable` / `disabled` | `false` | SelectPicker, fields |
| `columns` / `height` | `8` / `380` (`420` in sheet) | EmojiPicker |
| `maxRecent` | `24` | EmojiPicker |
| `maxHeightRatio` | `0.9` | BottomSheet |
| `bottomInset` | `24` iOS · `12` other | BottomSheet |

---

## Theme API

For concepts and the full token table, see the [Theming guide](../guides/theming).

### `PickersProvider`

```ts
function PickersProvider(props: {
  children: React.ReactNode;
  colorScheme?: 'auto' | 'light' | 'dark'; // default 'auto'
  theme?: DeepPartial<PickerTheme>;        // merged onto lightTheme (and onto darkTheme if `darkTheme` is omitted)
  darkTheme?: DeepPartial<PickerTheme>;    // merged onto darkTheme
}): JSX.Element;
```

Optional. Without a provider, components use `lightTheme` / `darkTheme` following `useColorScheme()`.

### `usePickerTheme`

```ts
function usePickerTheme(override?: DeepPartial<PickerTheme>): PickerTheme;
```

Returns the active theme: provider (or built-in) light/dark based on the colour scheme, with `override` merged on top. Use it in your own components to match the pickers.

### `createTheme`

```ts
function createTheme(overrides: DeepPartial<PickerTheme>, base?: PickerTheme): PickerTheme;
```

Builds a complete theme. Without `base`, starts from `darkTheme` if `overrides.dark` is `true`, else `lightTheme`.

### `mergeTheme`

```ts
function mergeTheme<T>(base: T, override?: DeepPartial<T>): T;
```

Deep merge without mutating. Plain objects merge recursively; arrays, functions and primitives in `override` replace the base value.

### `lightTheme` / `darkTheme`

```ts
const lightTheme: PickerTheme;
const darkTheme: PickerTheme;
```

The built-in themes. See [default values](../guides/theming#defaults).

### `textStyle`

```ts
function textStyle(
  theme: PickerTheme,
  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl',
  weight?: 'regular' | 'medium' | 'bold', // default 'regular'
): TextStyle; // { fontSize, fontWeight, fontFamily, color: theme.colors.text }
```

`medium` and `bold` use `typography.fontFamilyMedium`, falling back to `fontFamily`.

### Types

```ts
type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? (T[K] extends Function ? T[K] : DeepPartial<T[K]>) : T[K] };
interface ThemableProps { theme?: DeepPartial<PickerTheme> }
```

---

## Accessibility

Accessibility is built in. Here's what each component exposes to VoiceOver (iOS), TalkBack (Android) and screen readers on the web.

### Wheels

`WheelPicker` (and each column of `MultiWheelPicker`, `TimePicker` and `DateWheelPicker`) is a single element with:

| Property | Value |
| --- | --- |
| `accessibilityRole` | `adjustable` |
| `accessibilityValue` | the current label, e.g. `"45"` |
| `accessibilityActions` | `increment`, `decrement`: swipe up / down moves one row |
| `accessibilityLabel` | the `accessibilityLabel` prop |

Name your wheels, especially multi-column ones:

```tsx
<WheelPicker accessibilityLabel="Shirt size" items={sizes} value={size} onChange={setSize} />

<MultiWheelPicker
  columns={[
    { key: 'h', accessibilityLabel: 'Hours', items: hours, value: h, onChange: setH },
    { key: 'm', accessibilityLabel: 'Minutes', items: minutes, value: m, onChange: setM },
  ]}
/>
```

### Calendar

- Each day is a `button` labelled with the **full date** in the calendar's locale ("Wednesday, 14 October 2026"), with `selected` and `disabled` states.
- The arrows are buttons labelled **Previous** and **Next**, with a `disabled` state at min / max.
- The month title is a button (quick jump) or a `header`.
- Quick-jump grid cells expose `selected` / `disabled`.

### Select

- The field is a `button` labelled with `label` (or the placeholder). Its hint lists the selected options, and it has an `expanded` state.
- Options are `button`s in single mode and `checkbox`es in multiple mode, with `selected`, `checked` and `disabled`.
- Chips are buttons labelled `Remove {label}`, and × is labelled **Clear**.
- The search input is labelled with `searchPlaceholder`.

### Emoji

Every emoji cell is a button labelled with its name ("thumbs up"). Category tabs are `tab`s with a `selected` state, and the skin-tone button is labelled **Skin tone**.

### Sheets

The sheet is marked `accessibilityViewIsModal`, so focus stays inside it. The backdrop is a button labelled **Close**, string titles have the `header` role, and Android back closes the sheet.

### Your checklist

- Give every wheel an `accessibilityLabel`.
- Translate the English accessibility strings by passing translated `label` / `placeholder` / `searchPlaceholder` props.
- Keep custom `renderDay` / `renderOption` content as plain views and text. The library already provides the pressable and its accessibility props.
- Keep colour contrast when theming: `textSecondary` on `background` should meet WCAG AA (4.5:1) for body text.

---

## Forms (React Hook Form, Formik)

## Forms

Every picker is a controlled component, so it plugs into any form library. In a form you usually want a field that opens the picker: [`SelectPicker`](../components/select-picker) and the [picker fields](../components/picker-fields) (`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField`, `EmojiPickerField`) render one, and report the value through `onChange` (select) or `onConfirm` (fields). Their `onClose` is the natural place for `onBlur`.

### React Hook Form

```tsx
import { useForm, Controller } from 'react-hook-form';
import { Text, View, Button } from 'react-native';
import { SelectPicker, DatePickerField, TimePickerField } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

type FormValues = {
  country: string | null;
  tags: string[];
  date: Date | null;
  time: Date;
  stay: DateRange;
};

export function BookingForm() {
  const { control, handleSubmit, formState: { errors } } = useForm<FormValues>({
    defaultValues: { country: null, tags: [], date: null, time: new Date(), stay: { start: null, end: null } },
  });

  return (
    <View style={{ gap: 16 }}>
      <Controller
        control={control}
        name="country"
        rules={{ required: 'Pick a country' }}
        render={({ field }) => (
          <SelectPicker label="Country" options={countries} value={field.value} onChange={field.onChange} onClose={field.onBlur} />
        )}
      />
      {errors.country && <Text style={{ color: 'crimson' }}>{errors.country.message}</Text>}

      <Controller
        control={control}
        name="tags"
        rules={{ validate: (v) => v.length > 0 || 'Pick at least one tag' }}
        render={({ field }) => <SelectPicker multiple label="Tags" options={tags} value={field.value} onChange={field.onChange} />}
      />

      <Controller
        control={control}
        name="stay"
        rules={{ validate: (r) => (!!r.start && !!r.end) || 'Choose check-in and check-out' }}
        render={({ field }) => (
          <DatePickerField
            label="Stay"
            placeholder="Add dates"
            mode="range"
            value={field.value}
            onConfirm={field.onChange}
            onClose={field.onBlur}
            minDate={new Date()}
          />
        )}
      />
      {errors.stay && <Text style={{ color: 'crimson' }}>{errors.stay.message}</Text>}

      <Controller
        control={control}
        name="time"
        render={({ field }) => <TimePickerField label="Arrival" value={field.value} onConfirm={field.onChange} onClose={field.onBlur} />}
      />

      <Button title="Submit" onPress={handleSubmit(console.log)} />
    </View>
  );
}
```

`field.onChange` receives the first argument, which is the value, so extra arguments such as the `option` from `SelectPicker` are ignored.

#### Optional values

A field with `clearable` shows a × button while it has a value. Reset the form value in `onClear`:

```tsx
<Controller
  control={control}
  name="date"
  render={({ field }) => (
    <DatePickerField label="Due date" value={field.value} onConfirm={field.onChange} clearable onClear={() => field.onChange(null)} />
  )}
/>
```

#### Inline pickers

The inline pickers (`DatePicker`, `TimePicker`, `WheelPicker`…) take `value` + `onChange` the same way, for a picker that's always on screen:

```tsx
<Controller control={control} name="time" render={({ field }) => <TimePicker value={field.value} onChange={field.onChange} />} />
```

### Formik

```tsx
<Formik initialValues={{ birthday: new Date(2000, 0, 1), size: 'M' }} onSubmit={save}>
  {({ values, setFieldValue }) => (
    <>
      <DatePickerField label="Birthday" display="wheel" value={values.birthday} onConfirm={(d) => setFieldValue('birthday', d)} />
      <WheelPickerField label="Size" items={['S', 'M', 'L']} value={values.size} onConfirm={(v) => setFieldValue('size', v)} />
    </>
  )}
</Formik>
```

### Sending dates to an API

Pickers work with local `Date` objects. Serialize them for your API deliberately:

```ts
import { toDateKey } from '@elik56a/react-native-pickers';

// A calendar day (no time zone): '2026-10-14'
const day = toDateKey(date);

// An instant: '2026-10-14T07:30:00.000Z'
const instant = time.toISOString();

// Parse a 'YYYY-MM-DD' back to a local date (don't use new Date('2026-10-14'), which parses as UTC)
const [y, m, d] = '2026-10-14'.split('-').map(Number);
const local = new Date(y, m - 1, d);
```

:::caution Day keys vs ISO strings
`date.toISOString().slice(0, 10)` converts to UTC first, and can give **yesterday or tomorrow** depending on the user's time zone. Use `toDateKey` for calendar days.
:::

### Zod schema

```ts
import { z } from 'zod';

const schema = z.object({
  stay: z
    .object({ start: z.date().nullable(), end: z.date().nullable() })
    .refine((r) => r.start && r.end, 'Choose both dates'),
  country: z.string({ required_error: 'Pick a country' }),
});
```

---

## Haptics

Native wheels tick under your finger. Get the same feel with `onValueChanging`, which fires on **every row crossing** while scrolling. The library has no haptics dependency, so bring the one you already use.

### expo-haptics

```bash
npx expo install expo-haptics
```

```tsx
import * as Haptics from 'expo-haptics';
import { WheelPicker, TimePicker, DatePicker } from '@elik56a/react-native-pickers';

const tick = () => Haptics.selectionAsync();

<WheelPicker items={items} value={v} onChange={setV} onValueChanging={tick} />
<TimePicker value={t} onChange={setT} onValueChanging={tick} />
<DatePicker display="wheel" value={d} onChange={setD} onValueChanging={tick} />
```

### react-native-haptic-feedback

```tsx
import ReactNativeHapticFeedback from 'react-native-haptic-feedback';

const tick = () => ReactNativeHapticFeedback.trigger('selection', { enableVibrateFallback: false });
<WheelPicker onValueChanging={tick} … />
```

### Confirm haptics

For a stronger buzz when a value is confirmed, use `onChange` or a sheet's `onConfirm`:

```tsx
<DatePickerSheet
  …
  onConfirm={(range) => {
    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
    setRange(range);
  }}
/>
```

### Which components support `onValueChanging`

| Component | Callback argument |
| --- | --- |
| `WheelPicker` | `(value, index)` |
| `MultiWheelPicker` columns | `(value, index)` per column |
| `TimePicker` / `TimePickerSheet` | `(date)` |
| `DateWheelPicker` / `DatePicker display="wheel"` | `(date)` |
| `WheelPickerSheet` | `(value, index)` |

Disabled rows don't trigger `onValueChanging`.

---

## i18n & RTL

## Internationalization & RTL

Every name the pickers display comes from the JavaScript `Intl` API for the `locale` you pass (or the device default), and every UI string is a prop.

### What `locale` controls

| Component | Derived from `locale` |
| --- | --- |
| `Calendar` / `DatePicker` | Month title, weekday names, first day of week, day accessibility labels |
| `DateWheelPicker` | Month names, column order (D/M/Y vs M/D/Y vs Y/M/D) |
| `TimePicker` | 12h vs 24h, AM/PM labels |

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { DatePicker, TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [d, setD] = useState<Date | null>(new Date());
  const [t, setT] = useState(new Date());
  return (
    <View style={{ gap: 12 }}>
      <Text style={{ fontWeight: '600' }}>he-IL</Text>
      <DatePicker value={d} onChange={setD} locale="he-IL" />
      <Text style={{ fontWeight: '600' }}>ar-EG</Text>
      <TimePicker value={t} onChange={setT} locale="ar-EG" />
    </View>
  );
}
```

Pass your app's language, for example from `expo-localization` or `i18next`:

```tsx
import { getLocales } from 'expo-localization';
const locale = getLocales()[0]?.languageTag; // 'fr-CA'

<DatePicker locale={locale} … />
```

#### Hermes and `Intl`

Hermes (the default engine) supports `Intl.DateTimeFormat` on iOS and Android. If a locale or feature is missing at runtime, every helper falls back to English names instead of throwing. `firstDayOfWeek` uses `Intl.Locale` week info where available; otherwise it defaults to Sunday, so pass `firstDayOfWeek={1}` explicitly if you need Monday everywhere.

### Translating UI strings

| Component | String props (defaults) |
| --- | --- |
| Picker sheets | `confirmLabel` (`Done`), `cancelLabel` (`Cancel`), `title` |
| `SelectPicker` | `placeholder` (`Select…`), `label`, `sheetTitle`, `searchPlaceholder` (`Search`), `emptyText` (`No results`) |
| `SelectList` | `searchPlaceholder`, `emptyText` |
| `EmojiPicker` | `searchPlaceholder` (`Search emoji`), `emptyText` (`No emoji found`), `categoryLabels` |
| `TimePicker` | `dayPeriodLabels` (`[am, pm]`) |
| `Calendar` | `formatTitle` |

```tsx
const { t } = useTranslation();

<DatePickerSheet confirmLabel={t('done')} cancelLabel={t('cancel')} title={t('pickDate')} … />
<SelectPicker placeholder={t('select')} searchPlaceholder={t('search')} emptyText={t('noResults')} … />
```

### Right-to-left

All layouts use logical `start` / `end` properties, so they mirror automatically when `I18nManager.isRTL` is true:

- Calendar arrows swap direction, and swipe direction follows.
- The range band grows from the correct side.
- Select check marks, icons and chips sit on the logical end / start.
- Multi-wheel columns follow the row direction.

Enable RTL the standard React Native way:

```ts
import { I18nManager } from 'react-native';
I18nManager.allowRTL(true);
I18nManager.forceRTL(true); // requires an app reload
```

#### On the web

React Native Web has no RTL layout flag, and the browser aligns each label by its own script, so a list mixing Hebrew and English would zigzag. Select labels are therefore pinned to the left edge on the web. For an RTL web app, align them right through the slot styles:

```tsx
const rtl = { textAlign: 'right' } as const;

<SelectPicker styles={{ optionLabel: rtl, optionDescription: rtl, groupHeaderText: rtl, triggerText: rtl, placeholder: rtl }} … />
```

### Search in any language

The select search folds case and **diacritics** (`é` → `e`) and strips **Hebrew niqqud**, so users don't need to type accents. Use `keywords` to make options findable in other languages or by synonyms:

```ts
{ label: 'Germany', value: 'DE', keywords: ['Deutschland', 'Allemagne', 'גרמניה'] }
```

---

## Performance

### What the library does

- **Native-driver animations.** Wheel 3D transforms, fades, month slides and sheet transitions run on the UI thread on iOS and Android.
- **Virtualized lists.** Wheels and the emoji grid are `FlatList`s with `getItemLayout`, so only visible rows exist and scrolling never measures.
- **Memoized rows.** While a wheel scrolls, only the two rows whose selected state flips re-render. Calendar days and emoji cells are memoized too.
- **Lazy emoji data.** The 1,906-emoji table is parsed on first use and cached.
- **Formatter cache.** `Intl.DateTimeFormat` instances are cached per locale and options.

### What you can do

**Keep `items` / `options` stable.** Define them outside the component or `useMemo` them. New arrays every render make wheels re-normalize their items.

```tsx
// ✅ stable
const HOURS = Array.from({ length: 24 }, (_, i) => i);
function Example() {
  return <WheelPicker items={HOURS} … />;
}
```

**Memoize `theme` and `styles` objects**, especially on wheels:

```tsx
const theme = useMemo(() => ({ colors: { primary: brand } }), [brand]);
```

**Keep callbacks light.** `onValueChanging` fires on every row crossing; do haptics or cheap updates there, not network calls. Save in `onChange`.

**Keep `isDateDisabled` fast.** It runs for up to 42 days per render. Precompute a `Set` of `toDateKey`s.

**Mount sheets once.** Keep `<DatePickerSheet visible={open} … />` in the tree and toggle `visible`. It renders nothing while closed.

**Long select lists.** `SelectList` is virtualized. For thousands of options, give it a `listHeight` so the FlatList can window.

---

## Expo, bare RN & web

## Platforms

| Platform | Support | Notes |
| --- | --- | --- |
| **Expo Go** | ✅ | No native code, so nothing to prebuild |
| **Expo dev builds / EAS** | ✅ | |
| **Bare React Native** (iOS, Android) | ✅ | `react-native >= 0.72` |
| **New Architecture** (Fabric) | ✅ | Uses only core components |
| **Hermes** / JSC | ✅ | `Intl` names fall back to English where unsupported |
| **React Native Web** | ✅ | This site runs the library on RNW |
| **Expo Router web / Next.js** | ✅ | Via `react-native-web` |
| **react-native-windows / macos** | Untested | Core components only, so likely to work |

### Why pure JS matters

- **Same look everywhere.** Native date pickers look different on every OS version, and Android's calendar dialog can't be themed much. These pickers look exactly like your design on iOS, Android and web.
- **No native build.** Add the package and reload. Works in Expo Go and in OTA updates.
- **One code path.** No platform-specific bugs to chase, and tests run in Jest without native mocks.

### How it's built

Only React Native core APIs: `FlatList`, `Animated` (native driver on iOS/Android), `PanResponder`, `Modal`, `Pressable`, `TextInput` and `Intl`. No Reanimated, Gesture Handler, SVG or vector icons.

### Web specifics

- The wheel snaps to the nearest row once scrolling stops. Mouse wheel, trackpad and touch all work.
- `Modal` (used by sheets) renders into a portal on the web.
- Animations run on the JS driver on the web, because the native driver isn't available there.

#### Next.js / SSR

Render pickers on the client. They measure layout and animate, so wrap them in a client component:

```tsx
'use client';
import { DatePicker } from '@elik56a/react-native-pickers';
```

and alias `react-native` to `react-native-web` in your bundler config (Expo's and Next's RNW guides cover this).

### Testing

Components render in Jest with the `react-native` preset. Use `testID` props to find them:

```tsx
render(<SelectPicker testID="country" options={opts} value={null} onChange={onChange} />);
```

Wheels settle with timers, so use fake timers (`jest.useFakeTimers()` + `jest.runAllTimers()`) when asserting on `onChange` after a scroll event.

---

## Render props

When tokens and slots aren't enough, render props let you draw a part yourself. The component still handles touches, selection, scrolling and accessibility; you only render the visuals.

| Component | Prop | Signature |
| --- | --- | --- |
| `WheelPicker` | `renderItem` | `({ item, index, selected, theme }) => ReactNode` |
| `WheelPicker` | `renderIndicator` | `(theme) => ReactNode` |
| `Calendar` / `DatePicker` | `renderDay` | `(state: DayState, theme) => ReactNode` |
| `Calendar` / `DatePicker` | `renderArrow` | `(direction: 'prev' \| 'next', disabled: boolean) => ReactNode` |
| `Calendar` / `DatePicker` | `formatTitle` | `(month: Date, locale?: string) => string` |
| `SelectPicker` | `renderTrigger` | `({ open, selected, disabled }) => ReactNode` |
| `SelectPicker` | `renderChevron` | `({ open, theme }) => ReactNode` |
| `SelectPicker` / `SelectList` | `renderOption` | `({ option, selected, disabled, theme }) => ReactNode` |
| `SelectPicker` / `SelectList` | `renderGroupHeader` | `(group: string, theme) => ReactNode` |
| `*PickerField` / `PickerField` | `renderTrigger` | `({ open, displayValue, disabled }) => ReactNode` |
| `*PickerField` / `PickerField` | `renderChevron` | `({ open, theme }) => ReactNode` |
| `EmojiPicker` | `renderEmoji` | `(emoji: string, data: Emoji, size: number) => ReactNode` |
| `MultiWheelPicker` | `separator` | `ReactNode \| (leftIndex) => ReactNode` |
| `BottomSheet` | `title`, `headerLeft`, `headerRight`, `footer` | `ReactNode` |

Every render prop receives the resolved `theme`, so custom parts stay correct in dark mode.

### Calendar with availability prices

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { DatePicker } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

const price = (d: Date) => 80 + ((d.getDate() * 37) % 90);

export default function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });
  return (
    <DatePicker
      mode="range"
      value={range}
      onChange={setRange}
      minDate={new Date()}
      dayHeight={52}
      renderDay={(s, theme) => {
        const on = s.selected;
        const p = price(s.date);
        return (
          <View style={{ width: 44, height: 46, borderRadius: 12, alignItems: 'center', justifyContent: 'center', backgroundColor: on ? theme.colors.primary : 'transparent' }}>
            <Text style={{ fontWeight: '600', color: on ? theme.colors.onPrimary : s.disabled || s.outside ? theme.colors.textDisabled : theme.colors.text }}>
              {s.date.getDate()}
            </Text>
            {!s.disabled && !s.outside && (
              <Text style={{ fontSize: 9, color: on ? theme.colors.onPrimary : p < 100 ? '#16A34A' : theme.colors.textSecondary }}>${p}</Text>
            )}
          </View>
        );
      }}
    />
  );
}
```

### Wheel with icons

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { WheelPicker } from '@elik56a/react-native-pickers';

const moods = [
  { label: 'Awful', value: 1, icon: '😫' },
  { label: 'Bad', value: 2, icon: '😕' },
  { label: 'Okay', value: 3, icon: '😐' },
  { label: 'Good', value: 4, icon: '🙂' },
  { label: 'Great', value: 5, icon: '🤩' },
];

export default function Example() {
  const [mood, setMood] = useState(4);
  return (
    <WheelPicker
      items={moods}
      value={mood}
      onChange={setMood}
      itemHeight={56}
      variant="flat"
      renderItem={({ item, selected, theme }) => (
        <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 12 }}>
          <Text style={{ fontSize: selected ? 34 : 24 }}>{moods[item.value - 1].icon}</Text>
          <Text style={{ fontSize: 18, fontWeight: selected ? '700' : '400', color: selected ? theme.colors.text : theme.colors.textSecondary }}>{item.label}</Text>
        </View>
      )}
    />
  );
}
```

### Tips

- Keep render functions cheap. Wheels render a few rows, but they re-render as the selection moves.
- Don't add your own `Pressable` around the whole of `renderDay` / `renderOption` / `renderItem` content. The cell is already pressable, and a nested pressable swallows the tap.
- Read colours from the `theme` argument instead of hard-coding them, so dark mode keeps working.

---

## Styling with slots

Theme tokens set colours and sizes everywhere. **Slots** let you style one specific part of one component. Every component takes a `styles` prop: an object of slot name → style.

```tsx live
import { useState } from 'react';
import { WheelPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [v, setV] = useState('Wed');
  return (
    <WheelPicker
      items={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
      value={v}
      onChange={setV}
      styles={{
        indicator: { backgroundColor: '#111827', borderRadius: 999 },
        selectedItemText: { color: '#FFFFFF', fontWeight: '800', letterSpacing: 1 },
        itemText: { fontSize: 17 },
      }}
    />
  );
}
```

### Rules

- **Slot styles are merged last**, after the built-in and theme styles, so they always win.
- **State slots stack** on top of base slots: `selectedItemText` is applied after `itemText`, and `selectedDay` after `dayInner`.
- Slots accept any `StyleProp`: objects, arrays or `StyleSheet.create` entries.
- Types are exact. `SlotStyles<CalendarSlot>` autocompletes valid names and flags typos.
- `style` (singular) styles the outer container; `styles` (plural) are the slots.

```ts
type SlotStyles<K extends string> = Partial<Record<K, StyleProp<TextStyle>>>;
```

### All slots

| Component | Slots |
| --- | --- |
| [WheelPicker](../components/wheel-picker#slots) | `container` `item` `itemText` `selectedItemText` `disabledItemText` `indicator` |
| [MultiWheelPicker / TimePicker / DateWheelPicker](../components/multi-wheel-picker#slots) | `container` `indicator` `separator` `item` `itemText` `selectedItemText` `disabledItemText` |
| [Calendar / DatePicker](../components/date-picker#slots) | `container` `header` `headerTitle` `arrow` `arrowText` `weekdays` `weekdayText` `week` `day` `dayInner` `dayText` `selectedDay` `selectedDayText` `todayDay` `todayDayText` `disabledDayText` `outsideDayText` `rangeBand` `dot` `dayLabel` `gridCell` `gridCellText` |
| [SelectList](../components/select-list#slots) | `container` `search` `searchInput` `list` `groupHeader` `groupHeaderText` `option` `selectedOption` `optionLabel` `selectedOptionLabel` `optionDescription` `check` `empty` `emptyText` |
| [SelectPicker](../components/select-picker#slots) | all SelectList slots + `trigger` `triggerText` `placeholder` `label` `chip` `chipText` `chevron` `clear` |
| [EmojiPicker](../components/emoji-picker#slots) | `container` `header` `searchInput` `skinToneButton` `skinToneMenu` `categoryBar` `categoryTab` `activeCategoryTab` `categoryIndicator` `sectionHeader` `sectionHeaderText` `emojiCell` `emojiText` `empty` `emptyText` |
| [BottomSheet](../components/bottom-sheet#slots) | `backdrop` `sheet` `handle` `header` `title` `content` `footer` |

Picker sheets style their `BottomSheet` through `sheetProps={{ styles: { … } }}` and their picker through the picker's own `styles`.

### Example: square calendar

```tsx live
import { useState } from 'react';
import { DatePicker, addDays } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

const square = {
  dayInner: { borderRadius: 6 },
  selectedDay: { borderRadius: 6 },
  todayDay: { borderRadius: 6, borderStyle: 'dashed' as const },
  rangeBand: { borderRadius: 0 },
  headerTitle: { fontWeight: '800' as const, fontSize: 18 },
  arrow: { borderRadius: 6 },
};

export default function Example() {
  const t = new Date();
  const [r, setR] = useState<DateRange>({ start: addDays(t, 1), end: addDays(t, 4) });
  return <DatePicker mode="range" value={r} onChange={setR} styles={square} />;
}
```

### Example: outlined select field

```tsx live
import { useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [v, setV] = useState<string[]>(['design']);
  return (
    <SelectPicker
      multiple
      label="TEAMS"
      options={['Design', 'Engineering', 'Marketing', 'Sales'].map((t) => ({ label: t, value: t.toLowerCase() }))}
      value={v}
      onChange={setV}
      styles={{
        label: { fontSize: 11, letterSpacing: 1.2, fontWeight: '700' },
        trigger: { borderWidth: 2, borderRadius: 4, minHeight: 56 },
        chip: { borderRadius: 4, backgroundColor: '#111827' },
        chipText: { color: '#FFFFFF' },
      }}
    />
  );
}
```

### Reusing styles

Define slot objects once and share them app-wide:

```ts title="pickerStyles.ts"
import type { SlotStyles, CalendarSlot, SelectSlot, SelectTriggerSlot } from '@elik56a/react-native-pickers';

export const calendarStyles: SlotStyles<CalendarSlot> = { headerTitle: { fontFamily: 'Inter-Bold' } };
export const selectStyles: SlotStyles<SelectSlot | SelectTriggerSlot> = { trigger: { minHeight: 52 } };
```

→ When a slot isn't enough, [replace the part with a render prop](./render-props).

---

## Theming

Pickers ship with a polished light and dark theme that follow the OS appearance automatically. Change any token for the whole app with `PickersProvider`, or for one component with its `theme` prop.

### PickersProvider

```tsx title="App.tsx"
import { PickersProvider } from '@elik56a/react-native-pickers';

export default function App() {
  return (
    <PickersProvider
      colorScheme="auto"
      theme={{
        colors: { primary: '#FF5A5F', primaryMuted: 'rgba(255,90,95,0.12)' },
        radius: { md: 8, sheet: 16 },
        typography: { fontFamily: 'Inter-Regular', fontFamilyMedium: 'Inter-SemiBold' },
      }}
      darkTheme={{
        colors: { primary: '#FF8A8E', background: '#000000', sheet: '#111111' },
      }}
    >
      <Navigation />
    </PickersProvider>
  );
}
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | `'auto'` follows `useColorScheme()`. |
| `theme` | `DeepPartial<PickerTheme>` | — | Overrides merged onto `lightTheme`. **Also applied to dark mode when `darkTheme` is not given.** |
| `darkTheme` | `DeepPartial<PickerTheme>` | — | Overrides merged onto `darkTheme`. |
| `children` | `ReactNode` | **required** | |

:::caution Light overrides leak into dark mode
If you pass only `theme`, the same overrides are applied on top of the dark base too. That's right for brand colours and fonts, but wrong for backgrounds. Pass `darkTheme` whenever you override surface colours.
:::

Providers can be nested; the innermost one wins. That's an easy way to force one area dark:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { PickersProvider, DatePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <PickersProvider colorScheme="dark">
      <View style={{ backgroundColor: '#181612', borderRadius: 20, padding: 8 }}>
        <DatePicker value={date} onChange={setDate} />
      </View>
    </PickersProvider>
  );
}
```

### Per-component `theme`

Every component accepts `theme`, merged on top of the provider's theme for that component only:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { TimePicker } from '@elik56a/react-native-pickers';

export default function Example() {
  const [t, setT] = useState(new Date());
  return (
    <View style={{ gap: 16 }}>
      <TimePicker value={t} onChange={setT} theme={{ colors: { indicator: 'rgba(16,185,129,0.15)' }, typography: { sizes: { lg: 24 } } }} />
      <TimePicker value={t} onChange={setT} theme={{ colors: { indicator: 'rgba(244,63,94,0.12)', text: '#E11D48' }, radius: { md: 0 } }} />
    </View>
  );
}
```

:::tip Memoize theme objects
Pass a constant or `useMemo`'d object rather than an inline literal, so the merged theme isn't recomputed every render. It matters most on wheels.
:::

### Tokens

```ts
interface PickerTheme {
  dark: boolean;
  colors: {
    background: string;    // picker surfaces
    surface: string;       // search inputs, chips, pressed rows
    sheet: string;         // bottom sheet background
    text: string;
    textSecondary: string; // labels, unselected wheel rows, placeholders
    textDisabled: string;
    primary: string;       // selected day, check marks, buttons, accents
    onPrimary: string;     // text on primary
    primaryMuted: string;  // range band, selected list row, chips
    border: string;
    backdrop: string;      // sheet overlay
    indicator: string;     // wheel selection band
    handle: string;        // sheet grab handle
    hover: string;         // tint while the pointer is over anything pressable
    ripple: string;        // ripple that spreads from the touch point on press
  };
  radius: { sm: number; md: number; lg: number; full: number; sheet: number };
  spacing: { xs: number; sm: number; md: number; lg: number; xl: number };
  typography: {
    fontFamily?: string;
    fontFamilyMedium?: string; // used for medium and bold weights; falls back to fontFamily
    sizes: { xs: number; sm: number; md: number; lg: number; xl: number };
    weights: { regular: TextStyle['fontWeight']; medium: TextStyle['fontWeight']; bold: TextStyle['fontWeight'] };
  };
  animation: { duration: number }; // ms: month slide, sheet open (+60) / close
}
```

#### Defaults

| Token | Light | Dark |
| --- | --- | --- |
| `colors.background` | `#FFFFFF` | `#181612` |
| `colors.surface` | `#F4F2EE` | `#24211B` |
| `colors.sheet` | `#FFFFFF` | `#1D1B16` |
| `colors.text` | `#17150F` | `#F5F2EC` |
| `colors.textSecondary` | `#6E685E` | `#A39D92` |
| `colors.textDisabled` | `#BDB7AC` | `#534E45` |
| `colors.primary` | `#C8460D` | `#FF7A3D` |
| `colors.onPrimary` | `#FFFFFF` | `#17150F` |
| `colors.primaryMuted` | `rgba(200,70,13,0.12)` | `rgba(255,122,61,0.18)` |
| `colors.border` | `#E8E4DC` | `#2F2B24` |
| `colors.backdrop` | `rgba(23,21,15,0.45)` | `rgba(0,0,0,0.6)` |
| `colors.indicator` | `rgba(23,21,15,0.06)` | `rgba(255,255,255,0.07)` |
| `colors.handle` | `#D8D3C9` | `#3D3930` |
| `colors.hover` | `rgba(23,21,15,0.05)` | `rgba(255,255,255,0.06)` |
| `colors.ripple` | `rgba(23,21,15,0.18)` | `rgba(255,255,255,0.2)` |

| Token | Value (both) |
| --- | --- |
| `radius` | `sm 8 · md 12 · lg 16 · full 999 · sheet 24` |
| `spacing` | `xs 4 · sm 8 · md 12 · lg 16 · xl 24` |
| `typography.sizes` | `xs 11 · sm 13 · md 16 · lg 19 · xl 22` |
| `typography.weights` | `regular '400' · medium '500' · bold '600'` |
| `animation.duration` | `240` |

#### Where each colour is used

| Token | Used by |
| --- | --- |
| `primary` | Selected day, today ring, calendar arrows, check marks, chips text, Done button, category underline, tap-to-type ring |
| `primaryMuted` | Range band, selected select row, chips background, selected skin tone |
| `indicator` | Wheel selection band |
| `surface` | Search inputs, skin-tone button |
| `hover` | Every pressable while the pointer is over it: field, rows, days, wheel rows, emoji, buttons |
| `ripple` | The same elements on press, on every platform, except the select field and wheel rows |
| `textSecondary` | Unselected wheel rows, weekday names, placeholders, descriptions, Cancel |
| `textDisabled` | Disabled days / rows, outside-month days |

### Hover and ripple

Everything you can press (the select field, list and dropdown rows, calendar days, wheel rows, emoji, sheet buttons) tints while a pointer is over it. Items also ripple from the touch point when pressed; the select field and wheel rows don't, since the field opens a list and a wheel row scrolls into place. Hover only happens with a mouse or trackpad, so phones get just the ripple. Both are theme colours, so they follow light and dark mode:

```tsx live
import { useState } from 'react';
import { SelectList } from '@elik56a/react-native-pickers';

const fruits = ['Apple', 'Banana', 'Cherry', 'Mango'].map((f) => ({ label: f, value: f }));

export default function Example() {
  const [fruit, setFruit] = useState<string | null>('Banana');
  return (
    <SelectList
      options={fruits}
      value={fruit}
      onChange={setFruit}
      theme={{ colors: { hover: 'rgba(200,70,13,0.08)', ripple: 'rgba(200,70,13,0.22)' } }}
    />
  );
}
```

Set either to `'transparent'` to turn that effect off. Hover and press both lists to compare:

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { SelectList } from '@elik56a/react-native-pickers';

const sizes = ['Small', 'Medium', 'Large'].map((s) => ({ label: s, value: s }));

export default function Example() {
  const [a, setA] = useState<string | null>('Medium');
  const [b, setB] = useState<string | null>('Medium');
  return (
    <View style={{ flexDirection: 'row', gap: 16 }}>
      <View style={{ flex: 1 }}>
        <Text style={{ fontWeight: '600', marginBottom: 8 }}>Default</Text>
        <SelectList options={sizes} value={a} onChange={setA} />
      </View>
      <View style={{ flex: 1 }}>
        <Text style={{ fontWeight: '600', marginBottom: 8 }}>Turned off</Text>
        <SelectList
          options={sizes}
          value={b}
          onChange={setB}
          theme={{ colors: { hover: 'transparent', ripple: 'transparent' } }}
        />
      </View>
    </View>
  );
}
```

For the whole app, set them once on the provider:

```tsx
<PickersProvider theme={{ colors: { hover: 'transparent', ripple: 'transparent' } }}>…</PickersProvider>
```

Dark mode has its own defaults (a light tint instead of a dark one); override them through `darkTheme`:

```tsx
<PickersProvider
  theme={{ colors: { hover: 'rgba(14,165,233,0.08)', ripple: 'rgba(14,165,233,0.2)' } }}
  darkTheme={{ colors: { hover: 'rgba(56,189,248,0.12)', ripple: 'rgba(56,189,248,0.25)' } }}
>
  …
</PickersProvider>
```

### Building a theme in code

```ts
import { createTheme, mergeTheme, lightTheme, darkTheme } from '@elik56a/react-native-pickers';

// Full theme from overrides on top of light (or dark when overrides.dark is true)
const brand = createTheme({ colors: { primary: '#0EA5E9' } });

// Explicit base
const brandDark = createTheme({ colors: { primary: '#38BDF8' } }, darkTheme);

// Generic deep merge (objects are merged, arrays and primitives replaced)
const tweaked = mergeTheme(lightTheme, { radius: { md: 4 } });
```

### Using the theme in your own components

`usePickerTheme()` returns the active, resolved theme, so your buttons and fields can match the pickers:

```tsx
import { usePickerTheme, textStyle } from '@elik56a/react-native-pickers';

function DoneButton({ onPress }: { onPress: () => void }) {
  const theme = usePickerTheme();
  return (
    <Pressable onPress={onPress} style={{ backgroundColor: theme.colors.primary, borderRadius: theme.radius.md, padding: theme.spacing.md }}>
      <Text style={[textStyle(theme, 'md', 'bold'), { color: theme.colors.onPrimary }]}>Done</Text>
    </Pressable>
  );
}
```

`textStyle(theme, size, weight?)` returns `{ fontSize, fontWeight, fontFamily, color }` from the tokens.

### Matching your design system

Map your existing tokens once:

```tsx
import { colors, radii, fonts } from './design-system';

const pickerTheme = {
  colors: { primary: colors.brand500, primaryMuted: colors.brand50, text: colors.gray900, textSecondary: colors.gray500, border: colors.gray200 },
  radius: { md: radii.md, sheet: radii.xl },
  typography: { fontFamily: fonts.regular, fontFamilyMedium: fonts.semibold },
};
const pickerDarkTheme = { colors: { primary: colors.brand300, background: colors.gray950, sheet: colors.gray900 } };

<PickersProvider theme={pickerTheme} darkTheme={pickerDarkTheme}>…</PickersProvider>
```

→ For per-part tweaks beyond tokens, see [Styling](./styling).

---

## TypeScript

The library is written in TypeScript and ships its own declarations. No `@types` package is needed.

### Generic values

`WheelPicker`, `SelectPicker`, `SelectList`, `WheelPickerSheet` and `WheelPickerField` infer `T` from `items` / `options`:

```tsx
type Plan = 'free' | 'pro' | 'team';
const plans: SelectOption<Plan>[] = [
  { label: 'Free', value: 'free' },
  { label: 'Pro', value: 'pro' },
];

const [plan, setPlan] = useState<Plan | null>(null);
<SelectPicker options={plans} value={plan} onChange={setPlan} />; // onChange: (value: Plan, option: SelectOption<Plan>) => void
```

Or pass it explicitly: `<WheelPicker<number> items={…} />`.

### Discriminated selection modes

`mode` narrows `value` and `onChange`:

```tsx
<DatePicker value={date} onChange={(d) => d} />                 // d: Date
<DatePicker mode="range" value={range} onChange={(r) => r} />   // r: DateRange
<DatePicker mode="multiple" value={dates} onChange={(ds) => ds} /> // ds: Date[]
<DatePicker mode="ranges" value={ranges} onChange={(rs) => rs} />  // rs: DateRange[]

<SelectPicker multiple options={o} value={tags} onChange={(values, options) => {}} /> // values: T[]
```

`DatePickerSheet` and `DatePickerField` narrow `value` and `onConfirm` the same way:

```tsx
<DatePickerField mode="range" value={range} onConfirm={(r) => r} /> // r: DateRange
```

Passing a `DateRange` without `mode="range"` is a type error.

### Exported types

```ts
import type {
  // theme
  PickerTheme, DeepPartial, PickersProviderProps, ThemableProps, SlotStyles,
  // wheel
  WheelPickerProps, WheelItem, WheelItemInput, WheelPickerSlot, WheelRenderItemInfo,
  MultiWheelPickerProps, WheelColumn, MultiWheelSlot,
  // time / date
  TimePickerProps,
  DatePickerProps, CalendarProps, CalendarBaseProps, CalendarSelectionProps, CalendarSlot,
  DateRange, MarkedDate, DayState, DateWheelPickerProps, DatePart,
  // select
  SelectPickerProps, SelectListProps, SelectListBaseProps, SelectValueProps,
  SelectOption, SelectSlot, SelectTriggerSlot, SelectTriggerInfo, SelectRenderOptionInfo,
  // emoji
  EmojiPickerProps, EmojiPickerSlot, Emoji, EmojiCategory, SkinTone,
  // sheets
  BottomSheetProps, BottomSheetSlot, SheetChromeProps, SheetPresentation, SelectPresentation, PickerSheetProps,
  DatePickerSheetProps, TimePickerSheetProps, DateTimePickerSheetProps, WheelPickerSheetProps, EmojiPickerSheetProps,
  // fields
  PickerFieldProps, PickerFieldBaseProps, PickerFieldSlot, PickerFieldTriggerInfo, ChevronInfo, WithPickerField,
  DatePickerFieldProps, TimePickerFieldProps, DateTimePickerFieldProps, WheelPickerFieldProps, EmojiPickerFieldProps,
} from '@elik56a/react-native-pickers';
```

### Wrapping components

Extend the prop types to build your own pre-configured pickers:

```tsx
import { DatePicker } from '@elik56a/react-native-pickers';
import type { CalendarBaseProps, DateRange } from '@elik56a/react-native-pickers';

type StayPickerProps = Omit<CalendarBaseProps, 'minDate'> & {
  value: DateRange;
  onChange: (r: DateRange) => void;
};

export function StayPicker(props: StayPickerProps) {
  return <DatePicker mode="range" minDate={new Date()} minRangeDays={1} {...props} />;
}
```

---

## Alarm & reminder time

A big clock you tap to change, with repeat days chosen through a multi-select list. The clock is the `renderTrigger` of a [`TimePickerField`](../components/picker-fields#custom-trigger), so the field handles the sheet and formats the time.

```tsx live
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import { TimePickerField, SelectList, getWeekdayNames } from '@elik56a/react-native-pickers';

const days = getWeekdayNames(undefined, 'long').map((label, value) => ({ label, value }));

export default function Alarm() {
  const [time, setTime] = useState(() => {
    const d = new Date();
    d.setHours(7, 30, 0, 0);
    return d;
  });
  const [repeat, setRepeat] = useState<number[]>([1, 2, 3, 4, 5]);

  return (
    <View style={styles.root}>
      <TimePickerField
        title="Alarm"
        confirmLabel="Set"
        value={time}
        onConfirm={setTime}
        minuteInterval={5}
        renderTrigger={({ open, displayValue }) => (
          <Pressable onPress={open} accessibilityRole="button" accessibilityLabel="Change alarm time" accessibilityHint={displayValue}>
            <Text style={styles.clock}>{displayValue}</Text>
          </Pressable>
        )}
      />
      <Text style={styles.caption}>Repeat</Text>
      <SelectList multiple options={days} value={repeat} onChange={setRepeat} />
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 8 },
  clock: { fontSize: 64, fontWeight: '200', textAlign: 'center', fontVariant: ['tabular-nums'] },
  caption: { fontSize: 12, fontWeight: '700', color: '#6E685E', textTransform: 'uppercase', marginTop: 8, marginStart: 16 },
});
```

### Next occurrence

To schedule a notification, compute the next matching weekday:

```ts
function nextAlarm(time: Date, repeat: number[], from = new Date()): Date {
  for (let i = 0; i < 8; i++) {
    const d = new Date(from.getFullYear(), from.getMonth(), from.getDate() + i, time.getHours(), time.getMinutes());
    if (d > from && (repeat.length === 0 || repeat.includes(d.getDay()))) return d;
  }
  return from;
}
```

---

## Birthday picker

A date-of-birth [field](../components/picker-fields) that opens a wheel sheet, enforces a minimum age of 13, and shows the age.

```tsx live
import { useState } from 'react';
import { DatePickerField, formatDate } from '@elik56a/react-native-pickers';

const MIN_AGE = 13;

const yearsAgo = (n: number) => {
  const d = new Date();
  d.setFullYear(d.getFullYear() - n);
  return d;
};

const ageOf = (b: Date) => {
  const now = new Date();
  const hadBirthday = now.getMonth() > b.getMonth() || (now.getMonth() === b.getMonth() && now.getDate() >= b.getDate());
  return now.getFullYear() - b.getFullYear() - (hadBirthday ? 0 : 1);
};

export default function Birthday() {
  const [birthday, setBirthday] = useState<Date | null>(null);
  return (
    <DatePickerField
      label="Date of birth"
      title="Birthday"
      placeholder="Select your birthday"
      display="wheel"
      value={birthday ?? new Date(2000, 0, 1)}
      displayValue={birthday ? `${formatDate(birthday, undefined, { dateStyle: 'long' })} · ${ageOf(birthday)} y/o` : ''}
      onConfirm={setBirthday}
      minDate={yearsAgo(110)}
      maxDate={yearsAgo(MIN_AGE)}
    />
  );
}
```

### Notes

- `value` starts the wheel on 2000 before anything is picked, so `displayValue` is what keeps the placeholder showing until the user confirms.
- `maxDate` 13 years ago disables later days and months on the wheel and clamps the value, so under-13 dates can't be confirmed.
- The wheel's column order follows the locale (M/D/Y in the US, D/M/Y in most of the world). Pass `wheelProps={{ order: ['day', 'month', 'year'] }}` to force one.
- Store birthdays as `toDateKey(birthday)` (`YYYY-MM-DD`). They're calendar days, not instants.

---

## Hotel booking range

Check-in / check-out with nightly prices under each day, booked nights that ranges can't cross, a 2-night minimum and a live total.

```tsx live
import { useMemo, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { DatePicker, addDays, formatDate, toDateKey } from '@elik56a/react-native-pickers';
import type { DateRange, MarkedDate } from '@elik56a/react-native-pickers';

const MIN_NIGHTS = 2;
const nightly = (d: Date) => (d.getDay() === 5 || d.getDay() === 6 ? 189 : 129);

export default function Booking() {
  const today = useMemo(() => new Date(), []);
  const [range, setRange] = useState<DateRange>({ start: null, end: null });

  const marks = useMemo(() => {
    const out: Record<string, MarkedDate> = {};
    for (let i = 0; i < 90; i++) {
      const d = addDays(today, i);
      out[toDateKey(d)] = i % 11 === 6 || i % 11 === 7 ? { disabled: true, label: '—' } : { label: `$${nightly(d)}` };
    }
    return out;
  }, [today]);

  const nights = range.start && range.end ? Math.round((+range.end - +range.start) / 864e5) : 0;
  let total = 0;
  for (let i = 0; i < nights; i++) total += nightly(addDays(range.start!, i));

  return (
    <View style={styles.card}>
      <DatePicker
        mode="range"
        value={range}
        onChange={setRange}
        minDate={today}
        maxDate={addDays(today, 89)}
        minRangeDays={MIN_NIGHTS}
        markedDates={marks}
        dayHeight={50}
      />
      <View style={styles.summary}>
        <Text style={styles.dates}>
          {range.start ? formatDate(range.start, undefined, { day: 'numeric', month: 'short' }) : 'Check-in'}
          {'  →  '}
          {range.end ? formatDate(range.end, undefined, { day: 'numeric', month: 'short' }) : 'Check-out'}
        </Text>
        <Text style={styles.total}>{nights ? `${nights} nights · $${total}` : `Min. ${MIN_NIGHTS} nights`}</Text>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  card: { gap: 8 },
  summary: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', paddingHorizontal: 8 },
  dates: { fontSize: 15, fontWeight: '600', color: '#6E685E' },
  total: { fontSize: 15, fontWeight: '700', color: '#C8460D' },
});
```

### What's going on

- **`markedDates`** puts the price under each day and marks booked days `disabled`. Range selection [never crosses a disabled day](../components/date-range-picker#ranges-never-cross-disabled-days): tapping past one starts a new range.
- **`minRangeDays`** ignores a check-out tap that's too close to check-in.
- **`dayHeight={50}`** leaves room for the label.
- Prices are summed per night with `addDays`, which is DST-safe.

### As a sheet with Done

On phones, open the calendar from a summary bar. **Done** stays disabled until both dates are chosen:

```tsx
<DatePickerSheet
  visible={open}
  onClose={() => setOpen(false)}
  title="Select dates"
  confirmLabel="Save dates"
  mode="range"
  value={range}
  onConfirm={setRange}
  minDate={today}
  minRangeDays={MIN_NIGHTS}
  markedDates={marks}
  dayHeight={50}
  sheetProps={{ height: 0.75 }}
/>
```

---

## Chat input with emoji

A message composer with an emoji button that toggles an inline emoji panel, and emojis inserted **at the cursor**, not just appended.

```tsx live
import { useRef, useState } from 'react';
import { Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
import { EmojiPicker } from '@elik56a/react-native-pickers';
import type { SkinTone } from '@elik56a/react-native-pickers';

export default function Composer() {
  const [text, setText] = useState('');
  const [showEmoji, setShowEmoji] = useState(true);
  const [tone, setTone] = useState<SkinTone>(0);
  const [recent, setRecent] = useState<string[]>(['😂', '❤️', '👍']);
  const selection = useRef({ start: 0, end: 0 });

  const insert = (emoji: string) => {
    const { start, end } = selection.current;
    setText((t) => t.slice(0, start) + emoji + t.slice(end));
    const caret = start + emoji.length;
    selection.current = { start: caret, end: caret };
  };

  return (
    <View style={styles.root}>
      <View style={styles.bar}>
        <Pressable onPress={() => setShowEmoji((v) => !v)} accessibilityLabel="Emoji" style={styles.icon}>
          <Text style={styles.iconText}>{showEmoji ? '⌨️' : '😊'}</Text>
        </Pressable>
        <TextInput
          value={text}
          onChangeText={setText}
          onSelectionChange={(e) => (selection.current = e.nativeEvent.selection)}
          placeholder="Message"
          style={styles.input}
          multiline
        />
      </View>
      {showEmoji && (
        <EmojiPicker
          height={300}
          onSelect={insert}
          skinTone={tone}
          onSkinToneChange={setTone}
          recent={recent}
          onRecentChange={setRecent}
          categoryBarPosition="bottom"
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 8 },
  bar: { flexDirection: 'row', alignItems: 'flex-end', gap: 8 },
  icon: { width: 40, height: 40, alignItems: 'center', justifyContent: 'center' },
  iconText: { fontSize: 22 },
  input: { flex: 1, minHeight: 40, maxHeight: 120, borderWidth: 1, borderColor: '#E8E4DC', borderRadius: 20, paddingHorizontal: 14, paddingVertical: 9, fontSize: 16 },
});
```

### In production

- Persist `recent` and `tone` (AsyncStorage, MMKV) so they survive restarts; see [Recently used](../components/emoji-picker#recently-used).
- When the panel opens, dismiss the keyboard with `Keyboard.dismiss()`. When the input is focused, hide the panel.
- Size the panel to the last keyboard height (`Keyboard.addListener('keyboardDidShow', e => …)`) so switching doesn't jump.
- On older Android, set `maxEmojiVersion` to avoid emojis the device can't render.

---

## Country selector

Flags generated from ISO codes, grouped by region, searchable in several languages.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const flag = (code: string) => String.fromCodePoint(...[...code].map((c) => 0x1f1e6 + c.charCodeAt(0) - 65));

const COUNTRIES = [
  ['US', 'United States', 'Americas', '+1', ['usa', 'america']],
  ['CA', 'Canada', 'Americas', '+1', []],
  ['BR', 'Brazil', 'Americas', '+55', ['brasil']],
  ['GB', 'United Kingdom', 'Europe', '+44', ['uk', 'britain', 'england']],
  ['DE', 'Germany', 'Europe', '+49', ['deutschland']],
  ['FR', 'France', 'Europe', '+33', []],
  ['ES', 'Spain', 'Europe', '+34', ['españa']],
  ['IL', 'Israel', 'Middle East', '+972', ['ישראל']],
  ['AE', 'United Arab Emirates', 'Middle East', '+971', ['uae', 'dubai']],
  ['IN', 'India', 'Asia', '+91', ['bharat']],
  ['JP', 'Japan', 'Asia', '+81', ['nippon', '日本']],
  ['AU', 'Australia', 'Oceania', '+61', []],
] as const;

const options = COUNTRIES.map(([code, name, region, dial, keywords]) => ({
  label: name,
  value: code,
  group: region,
  description: dial,
  keywords: [code, dial, ...keywords],
  icon: <Text style={{ fontSize: 22 }}>{flag(code)}</Text>,
}));

export default function CountrySelect() {
  const [country, setCountry] = useState<string | null>('IL');
  return (
    <SelectPicker
      label="Country"
      placeholder="Select a country"
      sheetTitle="Choose your country"
      searchPlaceholder="Search name, code or +dial"
      options={options}
      value={country}
      onChange={setCountry}
      searchable
      autoFocusSearch
      sheet={{ sheetProps: { height: 0.8 } }}
    />
  );
}
```

Try searching `deutsch`, `+44`, `uae` or `日本`.

### Tips

- Use `keywords` for ISO codes, dialing codes and native names. Search matches them all, accent-insensitively.
- `group` + `options` order controls the sections: sort by region, then name.
- For phone inputs, use `renderTrigger` to show just `🇮🇱 +972` next to your `TextInput`.
- For all ~250 countries, the list is virtualized; give the sheet a fixed height (`sheetProps.height`) so it opens at a consistent size.

---

## Duration & timer picker

`TimePicker` picks a time of day. For a **length of time** (timer, workout, cooking), use `MultiWheelPicker` with unit labels.

```tsx live
import { useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { MultiWheelPicker } from '@elik56a/react-native-pickers';

const range = (n: number) => Array.from({ length: n }, (_, i) => i);
const HOURS = range(24);
const SIXTY = range(60);

function Unit({ children }: { children: string }) {
  return <Text style={styles.unit}>{children}</Text>;
}

export default function Timer() {
  const [h, setH] = useState(0);
  const [m, setM] = useState(25);
  const [s, setS] = useState(0);
  const total = h * 3600 + m * 60 + s;

  return (
    <View>
      <MultiWheelPicker
        separator={(left) => <Unit>{['hours', 'min', 'sec'][left]}</Unit>}
        columns={[
          { key: 'h', items: HOURS, value: h, onChange: setH, accessibilityLabel: 'Hours', textAlign: 'right' },
          { key: 'm', items: SIXTY, value: m, onChange: setM, loop: true, accessibilityLabel: 'Minutes', textAlign: 'right' },
          { key: 's', items: SIXTY, value: s, onChange: setS, loop: true, accessibilityLabel: 'Seconds', textAlign: 'right' },
        ]}
      />
      <Text style={styles.summary}>{total ? `Timer: ${total.toLocaleString()} seconds` : 'Pick a duration'}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  unit: { fontSize: 14, fontWeight: '600', color: '#6E685E', width: 44 },
  summary: { textAlign: 'center', color: '#6E685E', marginTop: 8 },
});
```

The `separator` function receives the index of the column on its **left**, so each gap gets that column's unit. Add a trailing "sec" label after the last column with a fixed-`width` column or an absolutely positioned label.

---

## Filters bottom sheet

A "Filters" sheet with a category select, a date range and Reset / Apply, all applied at once. It uses `BottomSheet` for the layout and `useDraft` so nothing changes until **Apply**.

```tsx live
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import { BottomSheet, DatePicker, SelectList, useDraft, formatDate } from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

type Filters = { status: string[]; dates: DateRange };
const EMPTY: Filters = { status: [], dates: { start: null, end: null } };
const STATUSES = ['Open', 'In progress', 'Blocked', 'Done'].map((s) => ({ label: s, value: s }));

function Button({ title, onPress, primary }: { title: string; onPress: () => void; primary?: boolean }) {
  return (
    <Pressable onPress={onPress} style={[styles.btn, primary && styles.btnPrimary]}>
      <Text style={[styles.btnText, primary && styles.btnTextPrimary]}>{title}</Text>
    </Pressable>
  );
}

export default function FiltersExample() {
  const [open, setOpen] = useState(false);
  const [filters, setFilters] = useState<Filters>(EMPTY);
  const [draft, setDraft] = useDraft(filters, open);
  const count = filters.status.length + (filters.dates.start ? 1 : 0);

  return (
    <>
      <Button title={`Filters${count ? ` · ${count}` : ''}`} onPress={() => setOpen(true)} />
      <Text style={styles.summary}>
        {filters.status.join(', ') || 'Any status'} ·{' '}
        {filters.dates.start && filters.dates.end ? `${formatDate(filters.dates.start)} → ${formatDate(filters.dates.end)}` : 'Any date'}
      </Text>

      <BottomSheet
        visible={open}
        onClose={() => setOpen(false)}
        title="Filters"
        height={0.85}
        headerRight={<Button title="Reset" onPress={() => setDraft(EMPTY)} />}
        footer={
          <Button
            primary
            title="Apply"
            onPress={() => {
              setFilters(draft);
              setOpen(false);
            }}
          />
        }
      >
        <View style={styles.body}>
          <Text style={styles.h}>Status</Text>
          <SelectList multiple options={STATUSES} value={draft.status} onChange={(status) => setDraft({ ...draft, status })} />
          <Text style={styles.h}>Created</Text>
          <DatePicker mode="range" value={draft.dates} onChange={(dates) => setDraft({ ...draft, dates })} maxDate={new Date()} dayHeight={38} />
        </View>
      </BottomSheet>
    </>
  );
}

const styles = StyleSheet.create({
  body: { paddingHorizontal: 8 },
  h: { fontSize: 12, fontWeight: '700', textTransform: 'uppercase', color: '#6E685E', marginTop: 12, marginBottom: 4, marginStart: 12 },
  summary: { marginTop: 8, color: '#6E685E', textAlign: 'center' },
  btn: { paddingVertical: 12, paddingHorizontal: 16, borderRadius: 12, backgroundColor: '#F4F2EE', alignItems: 'center' },
  btnPrimary: { backgroundColor: '#C8460D' },
  btnText: { fontWeight: '600', color: '#17150F' },
  btnTextPrimary: { color: '#FFFFFF' },
});
```

### Why `useDraft`

`useDraft(filters, open)` copies `filters` into `draft` each time the sheet opens. Edits change only the draft; **Apply** commits it, and closing any other way discards it. It's the same mechanism the built-in picker sheets use.

:::tip Scrolling content
With a fixed `height`, the sheet's content area is `flex: 1`. If your filters are taller than the sheet, wrap the body in a `ScrollView`.
:::

---

## Tag & multi-select

## Tags & multi-select

Pick up to 3 interests from grouped options. They show as removable chips, with a clear-all button.

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { SelectPicker } from '@elik56a/react-native-pickers';

const INTERESTS: Record<string, string[]> = {
  Sports: ['Running', 'Cycling', 'Climbing', 'Surfing'],
  Arts: ['Photography', 'Painting', 'Music', 'Film'],
  Tech: ['AI', 'Mobile', 'Web', 'Hardware'],
};

const options = Object.entries(INTERESTS).flatMap(([group, items]) =>
  items.map((label) => ({ label, value: label.toLowerCase(), group }))
);

const MAX = 3;

export default function Tags() {
  const [tags, setTags] = useState<string[]>(['climbing', 'ai']);
  return (
    <View style={{ gap: 6 }}>
      <SelectPicker
        multiple
        label="Interests"
        placeholder="Add interests"
        sheetTitle={`Pick up to ${MAX}`}
        options={options}
        value={tags}
        onChange={setTags}
        maxSelected={MAX}
        clearable
      />
      <Text style={{ fontSize: 12, color: '#6E685E' }}>{tags.length}/{MAX} selected · tap a chip to remove it</Text>
    </View>
  );
}
```

### Behaviour

- `maxSelected` disables the remaining options once the limit is hit; deselecting re-enables them.
- Chip taps call `onChange` with the chip removed.
- In multiple mode, × calls `onChange([], [])` for you.
- `onChange`'s second argument gives the full `SelectOption` objects, which is useful when you need labels:

```tsx
onChange={(values, selected) => {
  setTags(values);
  analytics.track('Interests Changed', { labels: selected.map((o) => o.label) });
}}
```

---

## React Native Picker Libraries Compared

## Comparison

React Native apps usually combine several single-purpose packages for pickers. This page shows how one pure-JS package compares with each category, and when another tool is the better choice.

### At a glance

| | **React Native Pickers** | Native OS pickers¹ | Calendar libraries² | Select wrappers³ |
| --- | --- | --- | --- | --- |
| Wheel picker (any data) | ✅ | ✅ iOS · ⚠️ Android dropdown | ❌ | ✅ (native) |
| Time picker | ✅ | ✅ | ❌ | ❌ |
| Calendar | ✅ | ⚠️ OS dialog | ✅ | ❌ |
| Date **range** selection | ✅ built in | ❌ | ⚠️ via manual marking | ❌ |
| Multiple dates | ✅ | ❌ | ⚠️ manual | ❌ |
| Searchable select / multi-select | ✅ | ❌ | ❌ | ⚠️ varies |
| Emoji picker | ✅ | ❌ | ❌ | ❌ |
| Bottom sheets | ✅ built in | ❌ | ❌ | ❌ |
| Identical UI on iOS / Android / web | ✅ | ❌ | ✅ | ❌ |
| Full theming + dark mode | ✅ tokens + slots | ⚠️ limited | ✅ | ⚠️ limited |
| Native code | **None** | Yes | Usually none | Yes |
| Extra peer dependencies | **None** | — | Varies | Native picker module |

¹ e.g. `@react-native-community/datetimepicker`, `@react-native-picker/picker`. ² e.g. `react-native-calendars`. ³ e.g. `react-native-picker-select`.

### Choose React Native Pickers when

- you want **one consistent design** across iOS, Android and web, matching your brand
- you need **ranges, multiple dates, marked dates or prices** in a calendar
- you need **several kinds of pickers** and want one API, one theme and one dependency
- you ship through **Expo Go / OTA updates** or want to avoid native modules
- you want **sheets** without pulling in Reanimated and Gesture Handler

### Choose something else when

- **You must use the OS-native UI**, for example for strict platform conformance. Use `@react-native-community/datetimepicker` or `@react-native-picker/picker`.
- **You need an agenda / timeline / week calendar** with events laid out by hour. That's a scheduling component, not a picker.
- **You need a full-featured gesture bottom sheet** (snap points, scrollable content interplay, detents) for non-picker screens. A dedicated sheet library such as `@gorhom/bottom-sheet` fits that; our `BottomSheet` covers simple modal sheets.

### Migrating

See [Migration](./migration) for side-by-side prop mappings from the most common packages.

---

## Contributing

The repo is a pnpm workspace: the library at the root, an Expo example app in `example/` that renders against the library source (edits hot-reload), and this docs site in `website/`.

### Setup

```sh
git clone https://github.com/elik56a/react-native-pickers.git
cd react-native-pickers
pnpm install   # also installs the git hooks
```

### Scripts

| Command | What it does |
|---|---|
| `pnpm web` | Example app in the browser |
| `pnpm ios` | Example app in the iOS Simulator |
| `pnpm android` | Example app in the Android emulator |
| `pnpm docs` | This site at `localhost:3001` |
| `pnpm test` | Jest + React Native Testing Library |
| `pnpm lint` | Biome: lint, format and import order |
| `pnpm format` | Fix whatever lint can fix |
| `pnpm typecheck` | TypeScript, including tests |
| `pnpm build` | Compile to `lib/` (ESM + `.d.ts`) |
| `pnpm gen:emoji` | Regenerate the emoji data from emojibase |

### Project structure

Each picker has its own folder under `src/`: `wheel`, `time`, `calendar`, `date`, `datetime`, `select` and `emoji`. They build on `sheet` (bottom sheets) and `core` (theme, shared hooks and utils). Imports only flow one way: feature → `sheet` → `core`.

Every folder has the same layout:

```
src/select/
├─ SelectPicker.tsx        components render only
├─ components/             smaller render-only parts
├─ hooks/                  state and event handling
├─ select.utils.ts         pure logic
├─ select.utils.test.ts    unit tests for every util
├─ select.types.ts
├─ select.constants.ts
├─ select.styles.ts
├─ SelectPicker.test.tsx   interaction tests
└─ index.ts                the folder's public API
```

Where new code goes:

- **Pure logic** (calculations, filtering, date math) goes in `<feature>.utils.ts`, with a unit test next to it.
- **State and event handling** goes in a hook under `hooks/`.
- **Components** only render: they call hooks and utils, with no inline logic.
- **Types, constants and styles** go in their own `<feature>.*.ts` files, never inside components.

### Conventions

- Tests sit next to the file they test.
- Use arrow functions: `export const fn = () =>`, not `export function`.
- Returned objects with two or more properties go one property per line. A Biome plugin enforces it, and `pnpm format` fixes it.
- Imports come in three blocks separated by a blank line: React and React Native, other packages, then our own code.
- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org): `feat:`, `fix:`, `refactor(select):`, `docs:` and so on.

### Checks

The pre-commit hook formats and lints the staged files and runs typecheck, and the commit-msg hook checks the message. On every pull request, CI runs lint, typecheck, tests and the build. Pull requests are squash-merged, so CI also checks that the PR title is a Conventional Commit: it becomes the commit message on `master`.

### Releasing

Releases are automated with [release-please](https://github.com/googleapis/release-please) and driven by the commit messages on `master`:

- `fix:` makes a patch release, `feat:` a minor one, and a `!` or a `BREAKING CHANGE:` footer a major one (a minor one before 1.0).
- Commits that only touch `website/`, `example/`, `.github/` or `lint/` don't trigger a release.
- After every merge, release-please updates a `chore(release): vX.Y.Z` pull request with the version bump and the [changelog](/changelog) entry. Nothing ships while it stays open.
- Merging that PR tags the version, creates the GitHub release, publishes to npm and redeploys these docs.
- To pick the version yourself, add a `Release-As: 1.0.0` footer to a commit.

The docs are versioned from the git tags: `/docs` always matches the latest release on npm, `master` is published as **Next** at `/docs/next`, and every minor line keeps its own version in the dropdown.

---

## React Native Pickers FAQ

## FAQ

### Does it work in Expo Go?

Yes. There's no native code, so it runs in Expo Go, dev builds, bare React Native and the web without a rebuild.

### Does it need Reanimated or Gesture Handler?

No. It uses only React Native core: `Animated` (native driver), `PanResponder`, `FlatList` and `Modal`.

### How do I clear a date?

Set `value` to `null` (single mode) or `{ start: null, end: null }` (range). The calendar shows no selection.

### How do I clear a single SelectPicker with the × button?

Single mode × calls only `onClear`, so reset your state there: `clearable onClear={() => setValue(null)}`. Multiple mode clears for you.

### Why doesn't `onChange` fire when I set `value`?

By design: `onChange` reports **user** changes only. Programmatic changes to `value` move the picker silently, which avoids feedback loops.

### Why doesn't `onChange` fire while the wheel is spinning?

`onChange` fires once the wheel settles. Use `onValueChanging` for per-row updates (haptics, live labels).

### What time zone are dates in?

Local time, the same as `new Date()`. Calendar days are compared by local year / month / day, so time zones never shift a selected day. Serialize days with [`toDateKey`](../api/date-utils#todatekey), not `toISOString()`.

### Does `TimePicker` change the date?

No. It only changes hours, minutes and seconds, and the date part of `value` is preserved.

### Can I select a date and a time together?

Use one `Date` in state for both:

```tsx
<DatePicker value={when} onChange={(d) => setWhen(new Date(d.getFullYear(), d.getMonth(), d.getDate(), when.getHours(), when.getMinutes()))} />
<TimePicker value={when} onChange={setWhen} />
```

### How big is it?

There are no dependencies. The emoji table (about 134 KB of source text) is the largest part. On the web it's dropped by tree-shaking if you don't import `EmojiPicker` or the emoji utilities.

### Can I use custom fonts?

Yes: `theme={{ typography: { fontFamily: 'Inter-Regular', fontFamilyMedium: 'Inter-SemiBold' } }}` on `PickersProvider`.

### How do I make the wheel bigger?

`itemHeight` sets the row height, `visibleItems` the row count, and `styles.itemText` the font size. The wheel's height is `itemHeight × visibleItems`.

### How do I use it in a ScrollView?

Just place it there. Wheels and the emoji grid scroll independently and don't trigger the "VirtualizedLists should never be nested" warning. For `SelectList` inside a `ScrollView`, set `listHeight`.

### Is it accessible?

Yes. Wheels are `adjustable` with increment / decrement actions, days announce full dates, and states are exposed throughout. See [Accessibility](../guides/accessibility).

### Does it support RTL?

Yes, automatically through `I18nManager.isRTL`. See [i18n & RTL](../guides/i18n-rtl).

---

## Migrate to React Native Pickers

## Migration

Prop-by-prop mappings from popular packages. Most migrations are a rename plus switching callbacks to `(value) => …`.

### From `@react-native-community/datetimepicker`

```diff
- import DateTimePicker from '@react-native-community/datetimepicker';
+ import { DatePicker, TimePicker } from '@elik56a/react-native-pickers';

- <DateTimePicker mode="date" value={date} onChange={(event, d) => d && setDate(d)} minimumDate={min} />
+ <DatePicker value={date} onChange={setDate} minDate={min} />

- <DateTimePicker mode="time" value={time} is24Hour onChange={(e, d) => d && setTime(d)} minuteInterval={5} />
+ <TimePicker value={time} onChange={setTime} format="24h" minuteInterval={5} />
```

| datetimepicker | React Native Pickers |
| --- | --- |
| `mode="date"` | `DatePicker` (calendar) or `DatePicker display="wheel"` |
| `mode="time"` | `TimePicker` |
| `mode="datetime"` | `DatePicker` + `TimePicker` sharing one `Date` (the time picker keeps the date part) |
| `display="spinner"` | `DatePicker display="wheel"` |
| `display="calendar"` / `"inline"` | `DatePicker` |
| `value` | `value` |
| `onChange(event, date)` | `onChange(date)` (no event, never `undefined`) |
| `minimumDate` / `maximumDate` | `minDate` / `maxDate` |
| `minuteInterval` | `minuteInterval` |
| `is24Hour` | `format="24h"` (default `'auto'` from locale) |
| `locale` | `locale` |
| `firstDayOfWeek` (Android) | `firstDayOfWeek` (0 = Sunday) |
| `themeVariant` | `PickersProvider colorScheme` |
| `accentColor` / `textColor` | `theme={{ colors: { primary, text } }}` |
| Android dialog (shown on mount) | `DatePickerSheet` / `TimePickerSheet` with `visible` |
| A button or input that opens the picker | `DatePickerField` / `TimePickerField` / `DateTimePickerField` ([picker fields](../components/picker-fields)) |

### From `react-native-modal-datetime-picker`

```diff
- <DateTimePickerModal isVisible={open} mode="date" date={date} onConfirm={setDate} onCancel={close} />
+ <DatePickerSheet visible={open} value={date} onConfirm={setDate} onClose={close} />
```

| modal-datetime-picker | React Native Pickers |
| --- | --- |
| `isVisible` | `visible` |
| `mode="date" \| "time"` | `DatePickerSheet` · `TimePickerSheet` |
| `date` | `value` |
| `onConfirm(date)` | `onConfirm(date)` (`onClose` is called right after) |
| `onCancel` | `onClose` |
| `confirmTextIOS` / `cancelTextIOS` | `confirmLabel` / `cancelLabel` |
| `minimumDate` / `maximumDate` | `minDate` / `maxDate` |

If `isVisible` was only toggled by a field that shows the date, drop the state and use [`DatePickerField`](../components/picker-fields) / `TimePickerField` / `DateTimePickerField` with the same props minus `visible`.

### From `react-native-calendars`

```diff
- <Calendar
-   current="2026-10-01"
-   minDate="2026-10-05"
-   onDayPress={(day) => setSelected(day.dateString)}
-   markedDates={{ [selected]: { selected: true }, '2026-10-22': { marked: true, dotColor: 'green' } }}
-   firstDay={1}
- />
+ <DatePicker
+   initialMonth={new Date(2026, 9, 1)}
+   minDate={new Date(2026, 9, 5)}
+   value={selected}
+   onChange={setSelected}
+   markedDates={{ '2026-10-22': { dots: ['green'] } }}
+   firstDayOfWeek={1}
+ />
```

| react-native-calendars | React Native Pickers |
| --- | --- |
| `current` (string) | `initialMonth` (`Date`) |
| `minDate` / `maxDate` (strings) | `minDate` / `maxDate` (`Date`) |
| `onDayPress(day)` | `onChange(date)`; selection is managed for you |
| `markedDates[k].selected` | `value` (no manual marking) |
| `markingType="period"` + manual start/end marking | `mode="range"` |
| `markedDates[k].marked` + `dotColor` | `markedDates[k].dots: [color]` |
| `markingType="multi-dot"` `dots: [{ color }]` | `dots: ['#hex', …]` (max 3) |
| `markedDates[k].disabled` / `disableTouchEvent` | `markedDates[k].disabled` or `isDateDisabled` |
| `firstDay` | `firstDayOfWeek` |
| `onMonthChange` | `onMonthChange(month: Date)` |
| `hideExtraDays` | `showOutsideDays={false}` |
| `enableSwipeMonths` | `enableSwipe` (on by default) |
| `dayComponent` | `renderDay(state, theme)` |
| `renderArrow(direction)` | `renderArrow(direction, disabled)` |
| `theme={{ selectedDayBackgroundColor, todayTextColor, … }}` | `theme={{ colors: { primary, … } }}` + `styles` slots |
| `LocaleConfig` | `locale="fr-FR"` (names from `Intl`) |

### From `react-native-picker-select`

```diff
- <RNPickerSelect
-   items={[{ label: 'Football', value: 'football' }]}
-   onValueChange={setSport}
-   value={sport}
-   placeholder={{ label: 'Select a sport…', value: null }}
- />
+ <SelectPicker
+   options={[{ label: 'Football', value: 'football' }]}
+   onChange={setSport}
+   value={sport}
+   placeholder="Select a sport…"
+ />
```

| react-native-picker-select | React Native Pickers |
| --- | --- |
| `items` | `options` (adds `description`, `icon`, `group`, `keywords`) |
| `onValueChange(value, index)` | `onChange(value, option)` |
| `value` | `value` |
| `placeholder={{ label }}` | `placeholder="…"` |
| `disabled` | `disabled` |
| `onOpen` / `onClose` | `onOpen` / `onClose` |
| `doneText` | `sheet={{ confirmLabel }}` (Done shown with `closeOnSelect={false}` / multiple) |
| `style={{ inputIOS, inputAndroid }}` | `styles={{ trigger, triggerText, placeholder }}` |
| — | `multiple`, `searchable`, `clearable`, `maxSelected`, `renderTrigger`, `renderOption` |

Want an iOS-style wheel instead of a list? Use [`WheelPickerSheet`](../components/picker-sheets#wheelpickersheet).

### From `@react-native-picker/picker`

```diff
- <Picker selectedValue={lang} onValueChange={setLang}>
-   <Picker.Item label="Java" value="java" />
-   <Picker.Item label="JavaScript" value="js" />
- </Picker>
+ <WheelPicker
+   items={[{ label: 'Java', value: 'java' }, { label: 'JavaScript', value: 'js' }]}
+   value={lang}
+   onChange={setLang}
+ />
```

`Picker.Item enabled={false}` → `{ disabled: true }`. Android `mode="dropdown"` → [`SelectPicker`](../components/select-picker).

---

## Troubleshooting

#### The wheel doesn't show my selected value

- Values are matched with `Object.is`. If `value` is an object (or a `Date`) re-created each render, pass `isEqual`:
  `isEqual={(a, b) => a.id === b.id}`.
- Check that `value` is the **value** of an item, not its label or index.
- If `value` points at a **disabled** item, the nearest enabled one is shown.

#### `onChange` fires with the wrong type

Primitive `items` (`['S', 'M']`, `[1, 2, 3]`) give you the primitive. With objects (`{ label, value }`), you get `value`. Mixing number and string items gives you a union.

#### Selected day is off by one

You probably built a date from an ISO string or key: `new Date('2026-10-14')` is **UTC midnight**, which is the previous day in the Americas. Use `new Date(2026, 9, 14)`, or parse `YYYY-MM-DD` into parts. When saving, use `toDateKey(date)` rather than `toISOString().slice(0, 10)`.

#### `markedDates` don't show

Keys must be **local** `YYYY-MM-DD` with zero padding (`2026-03-05`, not `2026-3-5`). Build them with `toDateKey`.

#### SelectPicker shows nothing after selecting

`SelectPicker` is controlled-only: you must update `value` in `onChange`.

#### The calendar doesn't jump to my new `value`

In single mode it follows `value` changes. In range / multiple mode it doesn't move automatically; remount with a `key` or set `initialMonth` when you need to show a specific month.

#### Sheet content is hidden by the keyboard (Android)

The sheet uses `KeyboardAvoidingView` on iOS. On Android, set `android:windowSoftInputMode="adjustResize"` (the Expo default), or give the sheet a fixed `height` via `sheetProps`.

#### The sheet is hidden behind the home indicator

Pass the safe-area inset: `sheetProps={{ bottomInset: insets.bottom + 8 }}` (or `bottomInset` on `BottomSheet`).

#### Emojis render as empty boxes

The device font doesn't support those emojis (older Android). Set `maxEmojiVersion`, for example `12` for Android 10.

#### Wheel feels sluggish in development

Debug builds run JS without optimizations. Try a release build, and make sure `items`, `theme` and `styles` are stable references (see [Performance](../guides/performance)).

#### Still stuck?

[Open an issue](https://github.com/elik56a/react-native-pickers/issues) with a minimal reproduction. A snippet from this site's live editor is perfect.