# React Native Pickers

> @elik56a/react-native-pickers: wheel, time, date (calendar, range, multiple, wheel), date-time, select (local or server search), horizontal list (segmented control, chips) and emoji pickers, plus bottom sheets and form fields, for React Native, Expo and React Native Web, with zero native code (pure JavaScript). Native iOS, Material and web designs by default (design="auto"), or one design everywhere; fully themeable.

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

## React Native Pickers, zero native code

## React Native Pickers

**One dependency-free package for every picker a React Native app needs** — wheel, time, duration, date (calendar, range, multiple, wheel), month, week strip, date & time, select / dropdown, segmented control and chips, emoji, color, the bottom sheets to put them in, and the form fields that open them. Each one looks native on iOS, Android and the web, and every detail is yours to customize.

<video
  src={useBaseUrl('/img/demo.mp4')}
  autoPlay
  loop
  muted
  playsInline
  width="100%"
  aria-label="React Native Pickers on an iPhone and an Android phone side by side: a date range picker with prices, wheel and clock-dial time pickers, a searchable select, an emoji picker, a phone number field, a color picker, a duration picker, and light and dark mode"
/>

**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) | 3D scrolling 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) | Wheels, a Material clock dial or columns to click; 12h / 24h 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** |
| [`MonthPicker`](./components/month-picker) | A month and year, like a card's expiry: wheels on iOS, a grid of months in Material and on the web |
| [`WeekStrip`](./components/week-strip) | One week of days in a row, with marked days; swipe or arrows to change weeks |
| [`DurationPicker`](./components/duration-picker) | A length of time, like a timer or a workout: wheels, Material number boxes or columns to click, the value in seconds |
| [`DateTimePicker`](./components/date-time-picker) | Day and time together: one row of wheels, or a calendar with the time under or beside it |
| [`SelectPicker`](./components/select-picker) | Form field that opens a searchable bottom sheet, modal or dropdown; single or multi-select with chips, groups, icons; [search a server](./recipes/server-search) with `loadOptions` |
| [`SelectList`](./components/select-list) | The same list, inline |
| [`CountryPicker`](./components/country-picker) | About 250 countries with flags and dialing codes, localized names, preferred countries on top |
| [`PhoneField`](./components/phone-field) | Phone number input: a country code button, the number formatted as it's typed, an E.164 value |
| [`TimeZonePicker`](./components/time-zone-picker) | Every IANA time zone with its GMT offset, sorted by offset, the device's zone on top |
| [`HorizontalList`](./components/horizontal-list) | Segmented control or chips that scroll sideways and reveal the next item |
| [`EmojiPicker`](./components/emoji-picker) | 1,923 emojis, categories, search, skin tones, recents, version filtering |
| [`ColorPicker`](./components/color-picker) | iOS's Grid / Spectrum / Sliders, Google's swatch circles, or the browser's spectrum; hex with opacity and a copy button |
| [`BottomSheet`](./components/bottom-sheet) | Animated sheet with drag-to-dismiss, for your own content |
| [`DatePickerSheet`, `TimePickerSheet`, `DateTimePickerSheet`, `DurationPickerSheet`, `MonthPickerSheet`, `ColorPickerSheet`, `WheelPickerSheet`, `EmojiPickerSheet`](./components/picker-sheets) | Ready-made pickers in a sheet with Cancel / Done and draft state |
| [`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `DurationPickerField`, `MonthPickerField`, `ColorPickerField`, `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, and ships in OTA updates.
- **Native on every platform.** iOS on iPhone, [Material Design](./guides/designs) on Android, a web design in the browser, all from one code path. Prefer one look everywhere? `<PickersProvider design="ios">` and the iOS design runs on Android and the web too.
- **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.
- **Yours to customize.** Light and dark themes are built in and follow the OS automatically. Override any token (colors, radius, spacing, fonts) globally with `PickersProvider` or per component, style any part through `styles`, and replace rows, days or triggers with render props. Your settings always win over the design.
- **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, designs, theming, slots
- [Designs](./guides/designs): the iOS, Material and web looks, and how to pick or customize one
- [Showcase](/showcase): real app screens built with the pickers, live on iOS, Android and the web
- [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)
Zero native code (pure JS), 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.
Looks native per platform by default (design 'auto': iOS on iOS, Material on Android, web on web). One look everywhere:
  <PickersProvider design="ios"> (or 'material' | 'web'); per component: design="material". theme/styles/explicit props always win over the design.
Every component takes: theme (DeepPartial<PickerTheme>), design ('ios'|'material'|'web'), styles (slot styles), style, testID.
Native apps: prefer subpaths so Metro skips unused pickers (root import bundles ~130 KB of emoji data):
  /wheel /time /date /calendar /datetime /select /list /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/HorizontalList 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?, suffix? }]  separator: node | (leftIndex)=>node  (suffix = unit text after a column)
TimePicker         value: Date  onChange(date)  format '12h'|'24h'|'auto'  minuteInterval  showSeconds  minTime/maxTime  locale
                   display 'wheel'(ios) | 'dial'(material clock) | 'input'(typed fields) | 'list'(web columns); default from the design
DurationPicker     a length of time, not a time of day: value: number (seconds)  onChange(seconds)  showHours=true  showSeconds=false
                   display 'wheel'(ios) | 'input'(material number boxes) | 'list'(web columns); default from the design
                   min max (seconds; default max 23h59m59s, or 59m59s without hours)  minuteInterval secondInterval  loop (minutes/seconds)
                   labels {hours:'h',minutes:'min',seconds:'s'}  formatDuration(5400) → '1 h 30 min'
DateTimePicker     value: Date  onChange(date)  display 'wheel'(ios default)|'calendar'(material/web default)  minDate maxDate (moments)
                   timePosition 'beside'|'below'  timeDisplay 'wheel'|'dial'|'input'|'list'  minuteInterval format locale calendarProps
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
MonthPicker        a month without a day: value: Date (first of the month)  onChange(month)  display 'wheel'(ios: month+year wheels) | 'grid'(material/web: months under the year, tap the year for years)
                   minDate maxDate (any day in the month)  yearRange  monthFormat 'long'|'short'|'numeric' (wheels)  locale
WeekStrip          one week of days in a row: value: Date|null  onChange(date)  swipe/arrows page weeks  onWeekChange(weekStart)  initialWeek
                   minDate maxDate isDateDisabled markedDates firstDayOfWeek locale showHeader formatTitle(weekStart) weekdayFormat renderDay (calendar's day cells and slots)
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})
                   presentation 'auto'(dropdown on web, bottom sheet on native)|'bottomSheet'|'modal'|'dropdown'
SelectList<T>      same list inline: options value onChange multiple listHeight
                   server search: loadOptions(query) => Promise<options>  (debounced by searchDebounce=300ms, loader until results, stale answers ignored; options = shown before typing; searchPrompt='Type to search' when none, emptyText after an empty search)
                   or manual: onSearchChange(query) + loading + onEndReached; loadingText renderLoading(theme); no local filtering with either
CountryPicker      a SelectPicker with ~250 countries built in: value CountryCode ('IL') or CountryCode[] with multiple  onChange(code, option)
                   preferred (pinned on top) countries exclude showDialCode locale (names via Intl.DisplayNames, English fallback; search matches English/native names, ISO code, +dial)
                   every SelectPicker prop except options/loadOptions/server search; getCountry(code) → {code,name,nativeName?,dialCode,flag,keywords}  getAllCountries()  getCountryFlag(code)
PhoneField         phone number input: flag + calling code button (CountryPicker list) then the number, formatted as typed ('(201) 555-0123', '54-123-4567')
                   value/defaultValue: E.164 string ('+972541234567', '' when empty)  onChange(value, {country, nationalNumber, valid})  valid = length fits the country
                   country/defaultCountry='US'/onCountryChange  label placeholder(default example) disabled presentation countrySheetTitle='Country code' sheet
                   preferred countries exclude locale preferredLabel allCountriesLabel; styles: label field input countryButton dialCode chevron
                   a leading trunk 0 is dropped (not IT/SM/VA); pasting '+44…' switches country; ~50 country formats, others grouped in threes
                   utils: parsePhone(intl, current?) → {country?, nationalNumber}  formatNationalNumber(digits, code)  isValidPhone(digits, code)  toE164(digits, code)
TimeZonePicker     a SelectPicker with all 418 IANA zones built in: value IANA name ('Europe/Lisbon') or string[] with multiple  onChange(id, option)
                   label = city, description 'GMT+1 · Central European Standard Time' (zone name where the engine has it, else region); sorted by offset
                   preferred (default: the device's zone, under 'Your time zone'; [] pins none) timeZones (only these) date (offsets for that moment, DST-aware) locale
                   old names ('Asia/Calcutta', 'Europe/Kiev') accepted as value, reported as current ('Asia/Kolkata'); search matches city, IANA name, region, GMT/UTC offset, zone name
                   utils: getDeviceTimeZone()  getTimeZoneOffset(id, date?) → minutes  formatGmtOffset(330) → 'GMT+5:30'  getTimeZoneName(id, locale?, date?)  normalizeTimeZone(id)  getTimeZone(id)  getAllTimeZones()
HorizontalList<T>  items: {label,value,disabled?,icon?}[] (icon: node or ({selected,disabled,color}) => node)  value  onChange(value, item)  variant 'segmented'|'chips'  iconPosition 'left'|'right'|'top'|'bottom'  showArrows (‹ › scroll buttons, default false)  arrowPosition 'outside'|'overlay' (default 'outside')  renderArrow(side, disabled)  renderItem  (tap at the edge scrolls the next item into view)
EmojiPicker        onSelect(emoji, data) columns=8 height=380 categories exclude maxEmojiVersion skinTone recent onRecentChange categoryBarPosition 'auto'(bottom on ios/material, top on web)|'top'|'bottom'
ColorPicker        value: hex ('#E4572E', or '#E4572E80' with showAlpha)  onChange('#RRGGBB'|'#RRGGBBAA', fires while dragging)
                   display 'tabs'(ios: Grid/Spectrum/Sliders) | 'swatches'(material: circles + Custom) | 'spectrum'(web: square, hue, hex, eyedropper); default from the design
                   colors (hex | {value,label})[]=DEFAULT_COLORS  showCustom=true  showAlpha=false  onCopy(hex) (copy button; web clipboard by default, native needs it, e.g. expo-clipboard)  labels  normalizeHex hexToHsv hsvToHex withAlpha
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
  ColorPickerSheet visible onClose value onConfirm(color) + ColorPicker props
  DateTimePickerSheet visible onClose value onConfirm + DateTimePicker props
  DurationPickerSheet visible onClose value onConfirm(seconds) + DurationPicker props
  MonthPickerSheet visible onClose value onConfirm(month) + MonthPicker 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 / DurationPickerField / MonthPickerField / ColorPickerField / 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
                     presentation 'auto'(dropdown on web, bottom sheet on native)|'bottomSheet'|'modal'|'dropdown'; design is passed on to the sheet
                   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={...} platform?='ios'|'android'|'web' design='auto'|'ios'|'material'|'web'>; per-component `theme` and `design` props. `platform` makes pickers behave as on that OS (preview native in a browser). `design` is the look: 'auto' = ios on iOS, web on web, material elsewhere; sheet actions in the header (ios: Cancel/Done) or footer (material: Cancel/OK), radios for single select and outlined floating-label fields in material, a date headline above Material calendars, TimePicker display: 'wheel' (ios) | 'dial' (material clock dial with a keyboard-entry toggle) | 'input' (typed hour/minute fields) | 'list' (web: hour/minute/AM-PM columns to click); dial and input fall back to wheels with showSeconds. DateTimePicker display defaults: 'wheel' on ios, 'calendar' in material (time input under it) and web (time columns beside it); timePosition 'beside'|'below' overrides where the time goes (beside moves below when both don't fit), timeDisplay 'wheel'|'dial'|'input'|'list' how it's picked. Calendar: ios tints the chosen day, material fills it and rings today with narrow S M T weekdays, web uses filled rounded squares, ripple in material and a dim while pressed on ios/web.
  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}
Keyboard (web, built in): arrows move focus through calendars, lists and grids by position (RTL-aware) and step wheels, sliders and the dial; Home/End; Esc closes sheets; focus returns to the field.
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,
  DateTimePicker,
  HorizontalList,
  PickersProvider,
  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);
  const [view, setView] = useState('day');

  return (
    <>
      <WheelPicker items={['S', 'M', 'L']} value={size} onChange={setSize} />
      <TimePicker value={time} onChange={setTime} minuteInterval={5} />
      <DateTimePicker value={time} onChange={setTime} />
      <HorizontalList items={[{ label: 'Day', value: 'day' }, { label: 'Week', value: 'week' }]} value={view} onChange={setView} />
      <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} />
    </>
  );
}

// Optional, once at the root: brand colors, and one design on every platform instead of the native one per OS
export const App = () => (
  <PickersProvider theme={{ colors: { primary: '#FF5A5F' } }} design="ios">
    <Examples />
  </PickersProvider>
);
```

---

## 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, and looks native on each platform (iOS, Material on Android, web). To use your brand colours everywhere, or one design on every platform, 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' } }}
      design="auto" // or 'ios' | 'material' | 'web' to use one look everywhere
    >
      <RootNavigator />
    </PickersProvider>
  );
}
```

See [Theming](../guides/theming) for every token and [Designs](../guides/designs) for the looks.

### 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,
  HorizontalList,
  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` |
| `/list` | `HorizontalList` |
| `/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)

### Pick a design

Each picker looks native on its platform by default. Use the switch at the top left of any example to see iOS, Android and Web. To use one look on every platform, set `design` on the provider or on one component:

```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
      design="material"
      value={time}
      onChange={setTime}
    />
  );
}
```

→ [Designs](../guides/designs)

### 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) |
| `HorizontalList` | `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. By default it opens a bottom sheet on iOS and Android and a dropdown under the field on the web; `presentation` picks `'bottomSheet'`, `'modal'` or `'dropdown'`.

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

### Designs

Pickers look native wherever they run: the iOS design on iOS, Material Design on Android, a web design in the browser. The design sets shapes and layout (where Done sits, a radio or a ✓, wheels or a clock dial), never your colors. Use one look everywhere, or for one component, with `design`:

```tsx
<PickersProvider design="ios">{/* the iOS look on Android and the web too */}</PickersProvider>
<TimePicker design="material" value={time} onChange={setTime} />
```

→ [Designs guide](../guides/designs)

### Theming

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

1. Built-in `lightTheme` / `darkTheme`, chosen from the OS appearance, with the [design](../guides/designs)'s shapes
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`, `renderLoading` |
| `HorizontalList` | `renderItem` |
| `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)

---

## iOS, Material & web designs

## Designs

Every picker looks native on the platform it runs on, from one code path: **iOS** on iPhone and iPad, **Material Design** on Android, and a **web** design in the browser. You don't write anything for this; it's the default.

A design changes shapes and layout: where Cancel and Done sit, how a field and a chosen day look, whether time is picked on wheels, a clock dial or columns. It never changes your colors, fonts or anything you set yourself.

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

const DESIGNS = [
  { label: 'iOS', value: 'ios' },
  { label: 'Material', value: 'material' },
  { label: 'Web', value: 'web' },
] as const;

export default function Example() {
  const [design, setDesign] = useState<Design>('material');
  const [date, setDate] = useState<Date | null>(null);
  const [time, setTime] = useState(new Date());
  return (
    <View style={{ gap: 16 }}>
      <HorizontalList
        items={DESIGNS}
        value={design}
        onChange={setDesign}
      />
      <DatePickerField
        design={design}
        label="Date"
        value={date}
        onConfirm={setDate}
      />
      <TimePicker
        design={design}
        value={time}
        onChange={setTime}
      />
    </View>
  );
}
```

### What each design changes

| | `ios` | `material` | `web` |
| --- | --- | --- | --- |
| Fields | label above, 48 tall | outlined, 56 tall; the label sits inside, then floats onto the border | label above, 40 tall, focus ring while open |
| Sheet corners | 24 | 28 | 12 |
| Cancel / confirm | beside a centered title, **Done** | after the content, **OK** | after the content, **Done** |
| Single select | ✓ beside the chosen option | a radio on every option | ✓ beside the chosen option |
| Option rows | rounded and tinted when chosen | edge to edge, untinted | compact, rounded and tinted |
| Calendar | chosen day tinted, today's number coloured, SUN MON | chosen day filled, today ringed, S M T | chosen day a filled square, today shaded, Sun Mon |
| Date sheet | calendar | the picked date in large type above the calendar | calendar |
| Time | wheels | a clock dial | columns of hours and minutes to click |
| Date & time | one row of wheels | calendar with time fields to type into under it | calendar with the time columns beside it |
| Duration | wheels with units | number boxes to type into | columns to click |
| Month | month and year wheels | a grid of months under the year | a grid of months under the year |
| WeekStrip | chosen day tinted, SUN MON | chosen day filled, S M T | chosen day a filled square, Sun Mon |
| Colour | Grid, Spectrum and Sliders tabs, swatches in a row to scroll | swatch circles, then **Custom** for a saturation square and hue slider | a saturation square, eyedropper, hue slider and hex code, then swatches |
| HorizontalList | a sliding raised thumb; filled chips | outlined segments and chips, the chosen one filled with a ✓ | a sliding raised thumb; filled chips |
| Search fields | a short gray search bar | a tall pill | an outlined input with a focus ring |
| EmojiPicker | categories at the bottom, the current one on a gray fill, UPPERCASE titles | categories at the bottom, the current one in a tinted pill | categories on top, underlined |
| Press | dims while held | ripple | dims while held |

`design="auto"` (the default) picks `ios` on iOS, `web` on the web, and `material` everywhere else (Android, Windows, macOS).

### One design everywhere

Set `design` on the provider to use one look on every platform. To keep the iOS look on Android and the web:

```tsx
<PickersProvider design="ios">
  <App />
</PickersProvider>
```

Or Material everywhere, for an app built on Material Design:

```tsx
<PickersProvider design="material">
  <App />
</PickersProvider>
```

### One component

`design` on a component wins over the provider's. A field passes its design to the sheet it opens.

```tsx
<SelectPicker design="material" options={options} value={value} onChange={setValue} />
<TimePickerField design="ios" label="Alarm" value={time} onConfirm={setTime} />
```

### Only part of a design

Some choices a design makes are props of their own, so you can keep the rest of a design and change just that:

| To get | Set |
| --- | --- |
| Wheels for time in any design | `display="wheel"` on `TimePicker` |
| A clock dial, typed fields or columns | `display="dial"`, `"input"` or `"list"` on `TimePicker` |
| One row of date and time wheels | `display="wheel"` on `DateTimePicker` |
| A calendar with time wheels | `display="calendar"` and `timeDisplay="wheel"` on `DateTimePicker` |
| The time beside or under the calendar | `timePosition="beside"` or `"below"` on `DateTimePicker` |
| `Mon` instead of `M` | `weekdayFormat="short"` on `DatePicker` |
| Your own button labels | `confirmLabel` / `cancelLabel` on any sheet or field |

### Customize a design

A design is a starting point. Everything you set wins over it:

- **Theme tokens.** `theme` and `darkTheme` on `PickersProvider` (colors, radius, spacing, fonts) are merged on top of the design's tokens. `radius.sheet` sets sheet corners in every design. See [Theming](./theming).
- **Slot styles.** Every visual part takes a style through `styles`. See [Styling with slots](./styling).
- **Render props.** Replace a row, a day, a trigger or a chevron and keep the behavior. See [Render props](./render-props).
- **Explicit props.** `confirmLabel`, `weekdayFormat`, `display` and the others above always win over the design's defaults.

`DESIGN_TOKENS` shows exactly what each design changes on the light or dark theme. In your own components, `usePickerTheme().design` tells you which design to match:

```tsx
const theme = usePickerTheme();
const radius = theme.design === 'material' ? theme.radius.full : theme.radius.md;
```

### Upgrading from 0.10

Before 0.11, every platform got the iOS look: wheels for times, one row of wheels for `DateTimePicker`, **Done** in the sheet header. Android and web apps now get the Material and web designs. To keep the old look, set `design="ios"` on the provider. To keep only part of it, use the props in [Only part of a design](#only-part-of-a-design).

### Upgrading from 0.12

`EmojiPicker` now follows the design too: on iOS and Android its category bar moves to the bottom, like the platform's own emoji keyboard, and search fields (in `EmojiPicker`, `SelectList` and `SelectPicker`) take each design's shape. To keep the bar on top, set `categoryBarPosition="top"`.

### Previewing other platforms

`design` sets the look. To also see how pickers *behave* on another platform in a browser (fields opening a bottom sheet instead of a dropdown, room for the iOS home indicator), set `platform` on the provider. See [Previewing other platforms](./platforms#previewing-other-platforms). The iOS / Android / Web switch on every live example on this site does both.

---

## 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

### 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`…). |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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 Color Picker

## ColorPicker

`ColorPicker` picks a colour the way each platform does: [iOS's colour picker, Google's swatch circles, or the browser's colour input](#three-layouts). The value is a hex string such as `'#E4572E'`.

It needs no native module, SVG or gradient library: the gradients are drawn as slices of solid colour.

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

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

export default function Example() {
  const [color, setColor] = useState('#2196F3');
  return <ColorPicker value={color} onChange={setColor} />;
}
```

### Try the props

### Three layouts

Each [design](../guides/designs) has its own, or pick one with `display`:

| `display` | Default in | What it is |
| --- | --- | --- |
| `'tabs'` | iOS | Like `UIColorPickerViewController`: **Grid** (one block of colours, the chosen one ringed in white), **Spectrum** (every hue across, white to black down) and **Sliders** (red, green and blue with the hex code), then the colour beside your swatches in a row to scroll |
| `'swatches'` | Material | Like Google's apps: circles with a check on the chosen one, and a **Custom** circle at the end that opens a saturation square, a hue slider and the hex code. A colour off the palette opens it already |
| `'spectrum'` | web | Like the browser's colour input: a saturation square, the colour beside a hue slider, the hex code, then your swatches. Where the browser has an eyedropper (Chrome, Edge), a button picks a colour from the screen |

Squares and the spectrum take a tap anywhere, as well as a drag. Screen readers step them across with increment and decrement, and up and down with two named actions.

### The value is a hex code

`value` and `defaultValue` take a hex code with 3 or 6 digits, with or without `#`, in any case. `onChange` always gives `'#RRGGBB'` in capitals, so you can compare it with `===`. Without `value` or `defaultValue`, the picker starts on blue, `#2196F3`.

`onChange` fires on every step while dragging, so the colour can preview live. Use [`ColorPickerSheet`](#in-a-sheet) or [`ColorPickerField`](#in-a-form-field) to commit only on **Done**.

### Opacity

`showAlpha` adds an opacity slider over a checkerboard. Below full opacity, the value gains two hex digits: `'#E4572E80'` is half see-through. Fully opaque colours stay six digits. Without `showAlpha`, a value with opacity is shown and returned opaque.

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

export default function Overlay() {
  const [color, setColor] = useState('#3F51B580');
  return <ColorPicker value={color} onChange={setColor} showAlpha />;
}
```

### Your own swatches

`colors` replaces the palette. Each colour is a hex code, or `{ value, label }` to give it a name for screen readers; a colour without a name is read as its code. They wrap to fill the width, except on iOS, where they sit in one row to scroll. `showCustom={false}` leaves only the swatches, in the design's shape.

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

const LABELS = [
  { value: '#D73A4A', label: 'Bug' },
  { value: '#0075CA', label: 'Documentation' },
  { value: '#A2EEEF', label: 'Enhancement' },
  { value: '#7057FF', label: 'Good first issue' },
  { value: '#008672', label: 'Help wanted' },
  { value: '#E4E669', label: 'Invalid' },
  { value: '#D876E3', label: 'Question' },
  { value: '#FFFFFF', label: 'Wontfix' },
];

export default function LabelColor() {
  const [color, setColor] = useState('#7057FF');
  return <ColorPicker value={color} onChange={setColor} colors={LABELS} showCustom={false} />;
}
```

The default palette is exported as `DEFAULT_COLORS`, to add to rather than replace.

### Copy the hex code

The hex field has a copy button in its corner. On the web it uses the browser's clipboard. React Native has no clipboard of its own without a native module, so on iOS and Android the button shows when you pass `onCopy`, for example from [`expo-clipboard`](https://docs.expo.dev/versions/latest/sdk/clipboard/):

```tsx
import * as Clipboard from 'expo-clipboard';

<ColorPicker value={color} onChange={setColor} onCopy={Clipboard.setStringAsync} />
```

`onCopy` also replaces the browser's clipboard on the web, to show your own toast, say.

### Other languages

`labels` renames the tabs, sliders and buttons, which screen readers read too:

```tsx
<ColorPicker
  value={color}
  onChange={setColor}
  labels={{ grid: 'Raster', spectrum: 'Spektrum', sliders: 'Regler', opacity: 'Deckkraft', copy: 'Kopieren', copied: 'Kopiert' }}
/>
```

The keys are `grid`, `spectrum`, `sliders`, `hue`, `saturation`, `brightness`, `opacity`, `red`, `green`, `blue`, `hex`, `copy`, `copied`, `eyedropper` and `custom`.

### In a sheet

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

<ColorPickerSheet visible={open} onClose={() => setOpen(false)} title="Label colour" value={color} onConfirm={setColor} />
```

It takes the [shared sheet props](./picker-sheets#shared-props) and the picker's, and keeps a draft until **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

### In a form field

`ColorPickerField` opens the sheet and shows the confirmed colour: a small swatch and its hex code.

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

### Utilities

| Export | Description |
| --- | --- |
| `normalizeHex(input)` | `'#RRGGBB'` in capitals for a 3- or 6-digit code with or without `#`, `'#RRGGBBAA'` for 4 or 8 digits below full opacity, or `null` |
| `hexToHsv(hex)` | `{ hue, saturation, brightness }`, each 0–1 |
| `hsvToHex(hsv)` | `'#RRGGBB'` |
| `withAlpha(hex, alpha)` | Adds an opacity 0–1: `withAlpha('#E4572E', 0.5)` is `'#E4572E80'` |
| `DEFAULT_COLORS` | The default palette: `{ value, label }[]` |

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Selected colour as hex (controlled). |
| `defaultValue` | `string` | `'#2196F3'` | Initial colour when uncontrolled. |
| `onChange` | `(color: string) => void` | — | Fires with `'#RRGGBB'`, or `'#RRGGBBAA'` below full opacity. |
| `display` | `'tabs' \| 'swatches' \| 'spectrum'` | from the design | iOS's tabs, Google's circles, or the browser's spectrum. |
| `colors` | `(string \| { value, label? })[]` | `DEFAULT_COLORS` | Your swatches. |
| `showCustom` | `boolean` | `true` | Show the grid, spectrum, sliders and hex field. Without them only `colors` show. |
| `showAlpha` | `boolean` | `false` | Add an opacity slider. |
| `onCopy` | `(hex: string) => unknown` | the browser's clipboard on the web | Copy the hex code; shows the copy button. |
| `labels` | `Partial<ColorLabels>` | English | Names of the tabs, sliders and buttons. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<ColorPickerSlot>` | — | `container`, `swatch`, `pad`, `slider`, `sliderThumb`, `sliderLabel`, `hexInput` and `preview`. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID. The parts get `${testID}-hex`, `-hue`, `-opacity`, `-pad`, `-spectrum`, `-red`, `-green` and `-blue`. |

`ColorPickerSheet` takes these plus the [sheet props](./picker-sheets#shared-props) and `onConfirm(color)`. `ColorPickerField` takes the sheet's props plus the [field props](./picker-fields#props).

### Related

- [EmojiPicker](./emoji-picker)
- [Picker fields](./picker-fields)

---

## React Native Country Picker

## CountryPicker

`CountryPicker` is a React Native form field for choosing a country: about 250 countries with flag emojis and international dialing codes, searchable by English or native name, ISO code or `+` dialing code. Country names follow the device's language. It's a [`SelectPicker`](./select-picker) with the country list built in, so it takes the same props: a bottom sheet on phones, a dropdown on the web, multiple selection, a clear button and the [iOS, Material or web design](../guides/designs).

No images or data files to add: flags are emoji, and the list is about 11 KB, parsed on first use.

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

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

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>('IL');
  return <CountryPicker label="Country" value={country} onChange={setCountry} />;
}
```

Try searching `deutschland`, `usa`, `+44` or `JP`. The value is the ISO 3166-1 alpha-2 code, such as `'IL'`. [`getCountry`](#utilities) turns it into the name, flag and dialing code.

### Try the props

### Preferred countries and dialing codes

`preferred` pins countries to the top under their own header, in the order you give. `showDialCode` adds each country's code under its name.

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

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>(null);
  return (
    <CountryPicker
      label="Phone country"
      preferred={['US', 'GB', 'CA']}
      showDialCode
      value={country}
      onChange={setCountry}
    />
  );
}
```

### Phone numbers

For a phone number, use [`PhoneField`](./phone-field): this country list behind a flag and calling code button, with the number formatted as it's typed and stored in E.164.

### Several countries

`multiple` turns the field into chips, as with `SelectPicker`. `maxSelected` caps the count.

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

export default function Example() {
  const [visited, setVisited] = useState<CountryCode[]>(['FR', 'JP']);
  return <CountryPicker label="Countries you've visited" multiple value={visited} onChange={setVisited} />;
}
```

### A subset of countries

`countries` limits the list to the ones you ship to, and `exclude` drops some. Both take ISO codes, and the list is always sorted by name.

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

const EU_SHIPPING: CountryCode[] = ['AT', 'BE', 'DE', 'ES', 'FR', 'IE', 'IT', 'NL', 'PT'];

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>(null);
  return <CountryPicker label="Ship to" countries={EU_SHIPPING} value={country} onChange={setCountry} />;
}
```

Pass `countries`, `exclude` and `preferred` from a constant, not a new array on every render, so the list is built once.

### Country names in other languages

Names come from `Intl.DisplayNames` in `locale`, the device locale by default. Search still matches the English and native names in every language. Where the JavaScript engine has no `Intl.DisplayNames`, names fall back to English.

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

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>('DE');
  return (
    <CountryPicker
      label="Land"
      placeholder="Land auswählen"
      searchPlaceholder="Suchen"
      locale="de"
      value={country}
      onChange={setCountry}
    />
  );
}
```

### Utilities

The country data is exported for your own UIs, such as a flag next to a username or a dialing code in a form.

| Export | Description |
| --- | --- |
| `getCountry(code)` | `{ code, name, nativeName?, dialCode, flag, keywords }` for an ISO code in any case, or `undefined` |
| `getAllCountries()` | Every `Country`, sorted by code |
| `getCountryFlag(code)` | The flag emoji for an ISO code: `'jp'` → 🇯🇵 |

```ts
getCountry('il'); // { code: 'IL', name: 'Israel', nativeName: 'יִשְׂרָאֵל', dialCode: '+972', flag: '🇮🇱', keywords: [] }
```

### Props

Every [`SelectPicker` prop](./select-picker#props) works, apart from the server search ones (`options`, `loadOptions`, `onSearchChange`, `loading` and the rest): the list is built in. `value` is a `CountryCode`, or `CountryCode[]` with `multiple`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `countries` | `CountryCode[]` | all | Only these countries. |
| `exclude` | `CountryCode[]` | — | Leave these out. |
| `preferred` | `CountryCode[]` | — | Shown first, in this order, under their own header. |
| `preferredLabel` | `string` | `'Suggested'` | Header above `preferred`. |
| `allCountriesLabel` | `string` | `'All countries'` | Header above the rest when `preferred` is set. |
| `showDialCode` | `boolean` | `false` | Show each country's dialing code under its name. |
| `locale` | `string` | device locale | Language of the country names. |
| `placeholder` | `string` | `'Select a country'` | Shown while nothing is selected. |
| `searchPlaceholder` | `string` | `'Search countries'` | Search field placeholder. |
| `sheet` | `SheetChromeProps` | `sheetProps.height: 0.8` | Sheet options. The sheet opens at 80% of the screen so it doesn't jump as search narrows the list. |

#### Types

```ts
type CountryCode = 'AD' | 'AE' | 'AF' | … ; // ISO 3166-1 alpha-2

interface Country {
  code: CountryCode;
  name: string; // English
  nativeName?: string; // in the country's own language, when different
  dialCode: string; // '+972'
  flag: string; // '🇮🇱'
  keywords: string[]; // aliases ('USA') and other dialing codes
}
```

Country data comes from [countries-list](https://github.com/annexare/Countries) (MIT).

---

## 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'` | from the design: `'narrow'` in Material, else `'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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Related

- [Date range & multiple](./date-range-picker)
- [MonthPicker](./month-picker): a month and year without a day
- [WeekStrip](./week-strip): one week of days in a row
- [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. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

All [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, and each [design](../guides/designs) has its own default:

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

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

```tsx live wide
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 wide
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 wide
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`). Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected date and time (controlled). |
| `defaultValue` | `Date` | now | Initial value when uncontrolled. |
| `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'` on iOS, `'calendar'` in Material and on the web | One row of wheels, or a calendar with the time. |
| `timePosition` | `'beside' \| 'below'` | `'beside'` on the web, `'below'` in iOS and Material | Calendar display: the time beside the calendar or under it. Beside moves under the calendar when there is no room for both. |
| `timeDisplay` | `'wheel' \| 'dial' \| 'input' \| 'list'` | wheels in iOS, `'input'` in Material, `'list'` on the web | Calendar display: how the time is picked. `'dial'` and `'input'` fall back to wheels with `showSeconds`. |
| `minDate` | `Date` | — | Earliest selectable moment. |
| `maxDate` | `Date` | — | Latest selectable moment. |
| `locale` | `string` | device | BCP 47 locale for day labels, clock format and the calendar. |
| `formatDay` | `(date: Date, locale?: string) => string` | `Today`, `Tue, Oct 27` | Day wheel labels (wheel display). |
| `calendarProps` | `Partial<CalendarBaseProps>` | — | Passed to the [Calendar](./date-picker#props) (calendar display). |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` (wheel); with the calendar `3` wheels or `5` web rows under it, `9` beside it | Visible rows. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots) of the wheels. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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 noplatforms
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 noplatforms
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 noplatforms
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.

### In a form field

`DatePickerField` with `display="wheel"` opens these wheels in a sheet from a field, and shows the confirmed date. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

| 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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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 Duration Picker

## DurationPicker

`DurationPicker` picks a **length of time**, such as a timer, a workout, a cooking time or a reminder: hours, minutes and optionally seconds, each with its unit beside it. It looks native on each platform: [wheels like the iOS countdown timer, number boxes to type into in Material, columns to click on the web](#wheels-boxes-or-columns), or the one you pick with `display`. The value is a number of seconds.

For a **time of day** (an alarm at 7:30 AM), use [`TimePicker`](./time-picker). A duration has no AM/PM and no locale clock, its hours don't wrap at midnight, and its limits are lengths, not times.

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

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

export default function Example() {
  const [seconds, setSeconds] = useState(25 * 60);
  return (
    <>
      <DurationPicker value={seconds} onChange={setSeconds} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {seconds} s = {formatDuration(seconds)}
      </Text>
    </>
  );
}
```

### Try the props

### The value is in seconds

`value`, `defaultValue` and `onChange` use a number of seconds: `5400` is 1 h 30 min. Store it as is, or turn it into text with [`formatDuration`](#formatduration). Without `value` or `defaultValue`, the picker starts at `0`.

### Wheels, boxes or columns

Each [design](../guides/designs) has its own default:

| `display` | Default in | What it is |
| --- | --- | --- |
| `'wheel'` | iOS | Hours, minutes and seconds wheels with their units at the selection band, like the iOS countdown timer |
| `'input'` | Material | A box per unit to type the number into, as in Material's time input. A number that isn't one of the steps yet (`3` on the way to `30` with `minuteInterval={15}`) waits for the next digit |
| `'list'` | web | A column of cells per unit under its label, the chosen one filled, as in `TimePicker` on the web |

```tsx
<DurationPicker value={seconds} onChange={setSeconds} display="wheel" />
```

### Hours, minutes and seconds

Hours and minutes show by default. `showSeconds` adds a seconds wheel, and `showHours={false}` drops the hours, so the minutes count past 59 (up to 90 for a 90-minute run):

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

export default function Example() {
  const [rest, setRest] = useState(90);
  return <DurationPicker value={rest} onChange={setRest} showHours={false} showSeconds secondInterval={5} />;
}
```

### Min, max and intervals

`min` and `max` are in seconds. Values outside them are dimmed, and a combination that lands outside (such as 2 h with 45 min while the max is 2 h) is pulled back to the nearest limit. Without `max`, the hours go up to 23, or the minutes up to 59 without hours.

`minuteInterval` and `secondInterval` show every n-th minute or second. A value between steps shows rounded **down**, and `DurationPickerSheet` confirms what the wheels show.

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

export default function Example() {
  const [workout, setWorkout] = useState(45 * 60);
  return <DurationPicker value={workout} onChange={setWorkout} min={10 * 60} max={3 * 3600} minuteInterval={5} />;
}
```

### Unit labels and other languages

`labels` sets the unit beside each wheel, box or column and in the field text. Screen readers read each one as "Hours", "Minutes" or "Seconds", followed by its value.

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

const GERMAN = { hours: 'Std.', minutes: 'Min.', seconds: 'Sek.' };

export default function Example() {
  const [seconds, setSeconds] = useState(3600);
  return <DurationPicker value={seconds} onChange={setSeconds} labels={GERMAN} />;
}
```

### `formatDuration`

Turns seconds into the field's text: the units that aren't zero, exact to the second.

```ts
formatDuration(5400); // '1 h 30 min'
formatDuration(95); // '1 min 35 s'
formatDuration(5400, { showHours: false }); // '90 min'
formatDuration(0); // '0 min'
```

It takes `showHours` and `labels`, like the picker.

### In a sheet

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

<DurationPickerSheet visible={open} onClose={() => setOpen(false)} title="Timer" value={seconds} onConfirm={setSeconds} />
```

It takes the [shared sheet props](./picker-sheets#shared-props) and the picker's, and keeps a draft until **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

### In a form field

`DurationPickerField` opens the sheet and shows the confirmed duration, like `1 h 30 min`. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | Selected duration in seconds (controlled). |
| `defaultValue` | `number` | `0` | Initial duration when uncontrolled. |
| `onChange` | `(seconds: number) => void` | — | Fires when any wheel settles. |
| `onValueChanging` | `(seconds: number) => void` | — | Fires on every tick while scrolling (haptics). |
| `display` | `'wheel' \| 'input' \| 'list'` | from the design | Wheels (iOS), boxes to type into (Material), or columns to click (web). |
| `showHours` | `boolean` | `true` | Show the hours wheel. Without it, minutes count past 59. |
| `showSeconds` | `boolean` | `false` | Add a seconds wheel. |
| `min` | `number` | `0` | Shortest selectable duration, in seconds. |
| `max` | `number` | 23 h 59 min 59 s, or 59 min 59 s without hours | Longest selectable duration, in seconds. |
| `minuteInterval` | `number` | `1` | Minute step: 1, 5, 15… |
| `secondInterval` | `number` | `1` | Second step. |
| `labels` | `{ hours?, minutes?, seconds? }` | `{ hours: 'h', minutes: 'min', seconds: 's' }` | Units beside the wheels and in the field. |
| `loop` | `boolean` | `true` | Loop the minute and second wheels. Hours never loop. |
| `itemHeight` | `number` | `40` | Wheel row height. |
| `visibleItems` | `number` | `5` | Visible wheel rows, or cells in a column. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots), for the wheels. The `separator` slot styles their unit labels. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID. Each wheel, box or column gets `${testID}-hours`, `-minutes` and `-seconds`. |

`DurationPickerSheet` takes these plus the [sheet props](./picker-sheets#shared-props) and `onConfirm(seconds)`. `DurationPickerField` takes the sheet's props plus the [field props](./picker-fields#props).

### Related

- [TimePicker](./time-picker): for a time of day
- [Duration & timer recipe](../recipes/duration)
- [MultiWheelPicker](./multi-wheel-picker): build other unit pickers with the column `suffix`

---

## React Native Emoji Picker

## EmojiPicker

`EmojiPicker` is a full React Native emoji keyboard: 1,923 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

### `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.

In `EmojiPickerSheet` and `EmojiPickerField`, the sheet keeps them, so they last between openings. A pick that closes the sheet shows up under **Recently used** the next time it opens, not while it closes, so the grid doesn't jump as it fades or slides away, as on the iOS emoji keyboard.

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}
/>
```

### Designs

Like every picker, it follows the [design](../guides/designs) of the platform it runs on, after that platform's own emoji picker:

| | `ios` | `material` | `web` |
| --- | --- | --- | --- |
| Categories | at the bottom, like the iOS emoji keyboard | at the bottom, like Gboard | on top |
| Current category | a gray rounded fill | a tinted pill | an underline |
| Search | a short gray search bar | a tall pill | an outlined input with a focus ring |
| Section titles | UPPERCASE | Sentence case | Sentence case |

Use the iOS / Android / Web switch on any example above to compare. `categoryBarPosition="top"` or `"bottom"` puts the bar in one place on every platform.

### 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`: `'auto'` (default) puts the bar where the [design](#designs) does, at the bottom on iOS and Android and on top on the web; `'top'` or `'bottom'` fixes it. 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. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

→ [Picker fields](./picker-fields#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` | `'auto' \| 'top' \| 'bottom'` | `'auto'` | Tab bar position. `auto`: bottom in the iOS and Material designs, top on the web. |
| `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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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 (web design; iOS and Material mark the tab itself) |
| `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 Horizontal List

## HorizontalList

`HorizontalList` is a row of choices that scrolls sideways: a segmented control by default, or a row of chips. When the user taps the item at the edge and more items are hidden past it, the list scrolls a little so the next item comes into view.

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

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

const views = [
  { label: 'Day', value: 'day' },
  { label: 'Week', value: 'week' },
  { label: 'Month', value: 'month' },
];

export default function Example() {
  const [view, setView] = useState('week');
  return <HorizontalList items={views} value={view} onChange={setView} accessibilityLabel="Calendar view" />;
}
```

### Segmented controls

A few items share the track's width. With more than fit, the track scrolls, and the thumb follows the selection along it.

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

const sorts = ['Popular', 'Newest', 'Price'].map((s) => ({ label: s, value: s }));
const ranges = ['1D', '1W', '1M', '3M', '6M', 'YTD', '1Y', '2Y', '5Y', '10Y', 'All'].map((r) => ({ label: r, value: r }));

export default function Example() {
  const [sort, setSort] = useState('Popular');
  const [range, setRange] = useState('1M');
  return (
    <View style={{ gap: 16 }}>
      <HorizontalList items={sorts} value={sort} onChange={setSort} accessibilityLabel="Sort by" />
      <HorizontalList items={ranges} value={range} onChange={setRange} accessibilityLabel="Chart range" />
    </View>
  );
}
```

### Chips

`variant="chips"` shows separate pills. With more items than fit, tap the last visible one: the list scrolls to show the next.

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

const cuisines = [
  'All', 'Italian', 'Japanese', 'Mexican', 'Indian', 'Thai', 'Chinese', 'Korean', 'Vietnamese', 'Greek',
  'Lebanese', 'Turkish', 'French', 'Spanish', 'Ethiopian', 'Peruvian', 'Brazilian', 'American', 'Vegan', 'Seafood',
].map((c) => ({ label: c, value: c }));

export default function Example() {
  const [cuisine, setCuisine] = useState('All');
  return <HorizontalList variant="chips" items={cuisines} value={cuisine} onChange={setCuisine} accessibilityLabel="Cuisine" />;
}
```

### Scroll arrows

`showArrows` adds round ‹ › buttons that scroll the list about a page. They're off by default: swiping already scrolls on touch screens, so arrows help most with a mouse on the web, or a long row of chips.

By default (`arrowPosition="outside"`) the arrows sit beside the list and show while its items overflow; the one that can't scroll further is dimmed, so the list keeps its width.

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

const countries = [
  ['🇺🇸', 'United States'], ['🇨🇦', 'Canada'], ['🇲🇽', 'Mexico'], ['🇧🇷', 'Brazil'], ['🇦🇷', 'Argentina'],
  ['🇬🇧', 'United Kingdom'], ['🇮🇪', 'Ireland'], ['🇫🇷', 'France'], ['🇩🇪', 'Germany'], ['🇪🇸', 'Spain'],
  ['🇵🇹', 'Portugal'], ['🇮🇹', 'Italy'], ['🇳🇱', 'Netherlands'], ['🇸🇪', 'Sweden'], ['🇳🇴', 'Norway'],
  ['🇬🇷', 'Greece'], ['🇹🇷', 'Turkey'], ['🇮🇱', 'Israel'], ['🇪🇬', 'Egypt'], ['🇿🇦', 'South Africa'],
  ['🇮🇳', 'India'], ['🇹🇭', 'Thailand'], ['🇻🇳', 'Vietnam'], ['🇯🇵', 'Japan'], ['🇰🇷', 'South Korea'],
  ['🇦🇺', 'Australia'], ['🇳🇿', 'New Zealand'],
].map(([flag, name]) => ({ label: name, value: name, icon: flag }));

export default function Example() {
  const [country, setCountry] = useState('Japan');
  return (
    <HorizontalList variant="chips" items={countries} value={country} onChange={setCountry} showArrows accessibilityLabel="Country" />
  );
}
```

#### Over the edges

`arrowPosition="overlay"` floats the arrows over the list's edges instead, each shown only while items are hidden past it, so the list keeps its full width.

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

const topics = [
  'For you', 'Following', 'Design', 'Engineering', 'React Native', 'TypeScript', 'Product', 'Startups', 'AI',
  'Open source', 'Accessibility', 'Performance', 'Testing', 'Animation', 'Career', 'Remote work', 'Writing',
].map((t) => ({ label: t, value: t }));

export default function Example() {
  const [topic, setTopic] = useState('For you');
  return (
    <HorizontalList
      variant="chips"
      items={topics}
      value={topic}
      onChange={setTopic}
      showArrows
      arrowPosition="overlay"
      accessibilityLabel="Topic"
    />
  );
}
```

#### Custom arrows

`renderArrow(side, disabled)` replaces the ‹ › glyph, and the `arrow` slot styles the button around it.

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

const genres = [
  'Pop', 'Rock', 'Hip-hop', 'Jazz', 'Classical', 'Electronic', 'R&B', 'Country', 'Reggae', 'Metal', 'Folk', 'Blues', 'Latin', 'K-pop',
].map((g) => ({ label: g, value: g }));

export default function Example() {
  const theme = usePickerTheme();
  const [genre, setGenre] = useState('Jazz');
  return (
    <HorizontalList
      variant="chips"
      items={genres}
      value={genre}
      onChange={setGenre}
      showArrows
      renderArrow={(side, disabled) => (
        <Text style={{ fontSize: 16, fontWeight: '700', color: disabled ? theme.colors.textDisabled : theme.colors.primary }}>
          {side === 'left' ? '←' : '→'}
        </Text>
      )}
      styles={{ arrow: { backgroundColor: theme.colors.primaryMuted, borderWidth: 0, boxShadow: 'none' } }}
      accessibilityLabel="Genre"
    />
  );
}
```

### Icons

Give an item an `icon` and choose its side with `iconPosition`: `'left'` (the default), `'right'`, `'top'` or `'bottom'`. `'left'` and `'right'` follow the layout direction, so they swap in RTL. An icon can also be a function of `{ selected, disabled, color }`, to color it like its label.

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

const modes = [
  { label: 'Walk', value: 'walk', icon: '🚶' },
  { label: 'Bike', value: 'bike', icon: '🚲' },
  { label: 'Bus', value: 'bus', icon: '🚌' },
  { label: 'Car', value: 'car', icon: '🚗' },
].map((m) => ({
  ...m,
  icon: ({ selected }: { selected: boolean }) => <Text style={{ fontSize: 18, opacity: selected ? 1 : 0.6 }}>{m.icon}</Text>,
}));

export default function Example() {
  const [mode, setMode] = useState('bike');
  return <HorizontalList items={modes} value={mode} onChange={setMode} iconPosition="top" accessibilityLabel="Travel mode" />;
}
```

Icons can be any view. Here each color filter has a swatch on its left:

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

const colors = [
  ['Black', '#1f1f1f'], ['White', '#f4f4f4'], ['Gray', '#9e9e9e'], ['Navy', '#1e3a8a'], ['Blue', '#3b82f6'],
  ['Green', '#16a34a'], ['Olive', '#708238'], ['Yellow', '#facc15'], ['Orange', '#f97316'], ['Red', '#dc2626'],
  ['Pink', '#ec4899'], ['Purple', '#9333ea'], ['Brown', '#8b5a2b'], ['Beige', '#d6c6a5'],
].map(([name, hex]) => ({
  label: name,
  value: name,
  icon: <View style={{ width: 14, height: 14, borderRadius: 7, backgroundColor: hex, borderWidth: 1, borderColor: 'rgba(0,0,0,0.15)' }} />,
}));

export default function Example() {
  const [color, setColor] = useState('Navy');
  return <HorizontalList variant="chips" items={colors} value={color} onChange={setColor} accessibilityLabel="Color" />;
}
```

### Disabled items

A `disabled` item is dimmed and can't be chosen, like sizes that are sold out.

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

const soldOut = ['XS', 'XXL'];
const sizes = ['XS', 'S', 'M', 'L', 'XL', 'XXL', '3XL'].map((s) => ({ label: s, value: s, disabled: soldOut.includes(s) }));

export default function Example() {
  const [size, setSize] = useState('M');
  return <HorizontalList variant="chips" items={sizes} value={size} onChange={setSize} accessibilityLabel="Size" />;
}
```

### Any value type

Values can be anything: numbers, ids, objects. `HorizontalList<T>` infers `T` from `items`, so `onChange` gets the typed value.

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

const bill = 64.5;
const tips = [0, 10, 15, 18, 20, 25, 30].map((percent) => ({ label: percent ? `${percent}%` : 'No tip', value: percent }));

export default function Example() {
  const theme = usePickerTheme();
  const [tip, setTip] = useState(18);
  return (
    <View style={{ gap: 12 }}>
      <HorizontalList items={tips} value={tip} onChange={setTip} accessibilityLabel="Tip" />
      <Text style={{ color: theme.colors.text, fontSize: 16 }}>Total: ${(bill * (1 + tip / 100)).toFixed(2)}</Text>
    </View>
  );
}
```

Object values are compared with `Object.is`. When they're recreated (say, refetched from a server), pass `isEqual`:

```tsx
<HorizontalList items={plans} value={plan} onChange={setPlan} isEqual={(a, b) => a.id === b.id} />
```

### Custom items

`renderItem` draws each item's content, and the `item` slot resizes the pill around it. Here, a strip of the next three weeks:

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

const dates = Array.from({ length: 21 }, (_, i) => {
  const date = new Date();
  date.setDate(date.getDate() + i);
  return date;
});
const days = dates.map((date, i) => ({ label: date.toDateString(), value: i }));

export default function Example() {
  const [day, setDay] = useState(0);
  return (
    <HorizontalList
      variant="chips"
      items={days}
      value={day}
      onChange={setDay}
      showArrows
      styles={{ item: { height: 60, minWidth: 48, borderRadius: 16 } }}
      renderItem={({ item, selected, theme }) => {
        const date = dates[item.value];
        const color = selected ? theme.colors.primary : theme.colors.text;
        return (
          <View style={{ alignItems: 'center', gap: 2 }}>
            <Text style={{ fontSize: 11, color: selected ? theme.colors.primary : theme.colors.textSecondary }}>
              {item.value === 0 ? 'Today' : date.toLocaleDateString(undefined, { weekday: 'short' })}
            </Text>
            <Text style={{ fontSize: 18, fontWeight: '700', color }}>{date.getDate()}</Text>
          </View>
        );
      }}
      accessibilityLabel="Day"
    />
  );
}
```

### Try the props

### Behaviour

- **Controlled**: pass `value` and update it in `onChange`. Tapping the selected item calls `onChange` again.
- In `segmented`, the thumb slides to the selected item; items share the track's width while they fit, and scroll when they don't.
- Tapping an item whose neighbor is hidden scrolls that neighbor into view, plus a little of the one after it, so the user sees there's more.
- With `showArrows`, the arrows need a frame around the list: `style` lays out that frame and `styles.container` styles the list itself.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ReadonlyArray<HorizontalListItem<T>>` | **required** | `{ label, value, disabled?, icon? }`. `icon` is a node, or a function of `{ selected, disabled, color }`. |
| `value` | `T \| null` | — | Selected value. |
| `onChange` | `(value: T, item) => void` | — | Called on tap. |
| `variant` | `'segmented' \| 'chips'` | `'segmented'` | Track with a sliding thumb, or separate pills. |
| `iconPosition` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Where each icon sits around its label. |
| `showArrows` | `boolean` | `false` | Round ‹ › buttons that scroll about a page, shown while the items overflow. |
| `arrowPosition` | `'outside' \| 'overlay'` | `'outside'` | Beside the list, the one that can't scroll further dimmed; or over its edges, each shown while items hide past it. |
| `renderArrow` | `(side: 'left' \| 'right', disabled: boolean) => ReactNode` | — | Custom arrow content. |
| `isEqual` | `(a: T, b: T) => boolean` | `Object.is` | Value equality. |
| `renderItem` | `(info: { item, selected, disabled, theme }) => ReactNode` | — | Custom item content. |
| `accessibilityLabel` | `string` | — | Names the list for screen readers. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<HorizontalListSlot>` | — | Slots below. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID; items get `{testID}-item-{index}`. |

#### Slots

| Slot | Element |
| --- | --- |
| `container` | The scroll view (the track in `segmented`) |
| `content` | The row inside it |
| `item` / `selectedItem` | Each item / the selected one |
| `itemLabel` / `selectedItemLabel` | Item label |
| `thumb` | The sliding thumb (`segmented`) |
| `arrow` / `arrowText` | Each scroll arrow / its glyph (`showArrows`) |

### Accessibility

The list is a `radiogroup` named by `accessibilityLabel`; items are `radio`s with `checked` and `disabled` states. Scroll arrows are buttons labelled "Scroll left" and "Scroll right".

### Related

- [Category filter chips](../recipes/category-chips): chips filtering a menu
- [Filters bottom sheet](../recipes/filters-sheet): a segmented sort order inside a sheet
- [Flight search form](../recipes/flight-search-form): trip type and cabin in a booking form

---

## React Native Month Picker

## MonthPicker

`MonthPicker` picks a **month and year** without a day: a card's expiry date, a report's month, a billing period, a graduation date. It looks native on each platform: [month and year wheels on iOS, a grid of months under the year in Material and on the web](#wheels-or-a-grid), or the one you pick with `display`.

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

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

export default function Example() {
  const [month, setMonth] = useState(new Date(2026, 9, 1));
  return (
    <>
      <MonthPicker value={month} onChange={setMonth} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>{formatMonthYear(month)}</Text>
    </>
  );
}
```

### Try the props

### The value is the first of the month

`value` and `onChange` use a `Date` on the first day of the month, at midnight: October 2026 is `new Date(2026, 9, 1)`. A `value` on another day shows its month. Read the parts with `getMonth()` (0–11) and `getFullYear()`.

### Wheels or a grid

Each [design](../guides/designs) has its own default:

| `display` | Default in | What it is |
| --- | --- | --- |
| `'wheel'` | iOS | Month and year wheels, in the order the locale writes them (year first in Japanese and Chinese), like the iOS date picker's month mode |
| `'grid'` | Material, web | The year with arrows, above its 12 months to tap. Tap the year for a page of 12 years |

```tsx
<MonthPicker value={month} onChange={setMonth} display="grid" />
```

`monthFormat` sets the wheel's month names: `'long'` (October), `'short'` (Oct) or `'numeric'` (10). The grid always shows short names.

### Min and max

`minDate` and `maxDate` limit the months: months outside them are disabled, and the arrows and year grid stop at their years. Any day of the month counts, so `minDate={new Date()}` allows the current month. Without them, the years go 100 back and 100 ahead, or set `yearRange`.

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

const now = new Date();
const inTenYears = new Date(now.getFullYear() + 10, 11, 1);

export default function CardExpiry() {
  const [expiry, setExpiry] = useState(new Date(now.getFullYear() + 3, 0, 1));
  return <MonthPicker value={expiry} onChange={setExpiry} minDate={now} maxDate={inTenYears} monthFormat="numeric" />;
}
```

### In a sheet

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

<MonthPickerSheet visible={open} onClose={() => setOpen(false)} title="Report month" value={month} onConfirm={setMonth} />
```

It takes the [shared sheet props](./picker-sheets#shared-props) and the picker's, and keeps a draft until **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

### In a form field

`MonthPickerField` opens the sheet and shows the confirmed month for `locale`, like `October 2026`. For a card's `10/29`, pass your own `displayValue`.

```tsx
<MonthPickerField
  label="Expiry"
  value={expiry}
  onConfirm={setExpiry}
  minDate={new Date()}
  displayValue={expiry ? `${String(expiry.getMonth() + 1).padStart(2, '0')}/${String(expiry.getFullYear()).slice(2)}` : ''}
/>
```

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected month (controlled): its first day. |
| `defaultValue` | `Date` | this month | Initial month when uncontrolled. |
| `onChange` | `(month: Date) => void` | — | Fires with the first day of the picked month. |
| `display` | `'wheel' \| 'grid'` | from the design | Wheels (iOS) or a grid of months (Material, web). |
| `locale` | `string` | device | Month names and the wheel order. |
| `minDate` / `maxDate` | `Date` | — | Earliest and latest selectable month: any day in it. |
| `yearRange` | `[number, number]` | ±100 years | Years when there's no min/max. |
| `monthFormat` | `'long' \| 'short' \| 'numeric'` | `'long'` | Wheel month names. |
| `loop` | `boolean` | `true` | Loop the month wheel. |
| `itemHeight` / `visibleItems` / `variant` | | `40` / `5` / `'3d'` | Wheel row height, rows and style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MonthPickerSlot>` | — | [Wheel slots](./multi-wheel-picker#slots), or the grid's `header`, `headerTitle`, `arrow`, `arrowText`, `gridCell` and `gridCellText`. |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID. The wheels get `${testID}-month` and `-year`. |

`MonthPickerSheet` takes these plus the [sheet props](./picker-sheets#shared-props) and `onConfirm(month)`. `MonthPickerField` takes the sheet's props plus the [field props](./picker-fields#props).

### Related

- [DatePicker](./date-picker): a day in a calendar
- [DateWheelPicker](./date-wheel-picker): day, month and year wheels
- [WeekStrip](./week-strip): a day from a week strip

---

## 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 noplatforms
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

### 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
  suffix?: string; // text after the column at the selection band, such as a unit
};
```

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 noplatforms
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>
    </>
  );
}
```

For a unit after each column, such as `min`, set the column's `suffix` instead: it's shown after the column at the selection band in the theme's secondary text color, and the `separator` slot styles it too. [`DurationPicker`](./duration-picker) labels its wheels this way.

### Column widths

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

```tsx live noplatforms
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 noplatforms
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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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 Phone Number Input

## PhoneField

`PhoneField` is a React Native phone number input: a country button with the flag and calling code, then the number, grouped the way that country writes it as the user types. The value is one string in E.164, such as `'+972541234567'`, ready to store or send to an SMS service.

The country list is [`CountryPicker`](./country-picker): searchable, in the device language, a bottom sheet on phones and a dropdown on the web. The field follows the [iOS, Material or web design](../guides/designs). No dependency and no metadata download: formats for about 50 countries add 2 KB.

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

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

export default function Example() {
  const [phone, setPhone] = useState('');
  return <PhoneField label="Phone" defaultCountry="IL" value={phone} onChange={setPhone} />;
}
```

Type `054 123 4567`: the leading 0 is dropped, the number shows as `54-123-4567`, and the value is `+972541234567`. Paste `+44 7911 123456` and the field switches to the United Kingdom.

### Try the props

### Checking the number

`onChange` passes the E.164 value and the details: the country, the digits after the calling code, and `valid`, whether the number has as many digits as that country's numbers do.

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

export default function Example() {
  const [phone, setPhone] = useState('');
  const [details, setDetails] = useState<PhoneDetails | null>(null);
  return (
    <View style={{ gap: 8 }}>
      <PhoneField
        label="Mobile"
        preferred={['US', 'GB', 'CA']}
        value={phone}
        onChange={(value, info) => {
          setPhone(value);
          setDetails(info);
        }}
      />
      <Text>{details ? `${details.country} · ${details.valid ? 'looks right' : 'too short or too long'}` : 'Type a number'}</Text>
    </View>
  );
}
```

`valid` checks the length only, which catches most typos. For carrier checks, verify on your server, as with an SMS code.

### The country

The country follows the number: a `value` or a pasted number with another calling code shows its own country. Before there is a number, `defaultCountry` picks it, or control it with `country` and `onCountryChange`, for example from the device region.

Countries sharing a calling code keep the one chosen: a US number with a Caribbean area code stays American. Picking another country keeps the digits and moves them to its calling code.

### How numbers are formatted

About 50 countries, those with the most phone users, have their own pattern: `(201) 555-0123` in the US, `6 12 34 56 78` in France, `54-123-4567` in Israel. Countries sharing a calling code with one of them use its pattern, so Canada and the Caribbean look American. The rest are grouped in threes. Grouping is only for display; the value is always digits.

A leading 0, the trunk prefix most countries dial at home, is dropped, except in Italy, San Marino and the Vatican, where it's part of the number.

### Utilities

| Export | Description |
| --- | --- |
| `parsePhone(international, current?)` | `{ country?, nationalNumber }` for a number like `'+44 7911 123456'` |
| `formatNationalNumber(digits, country)` | `'2015550123'`, `'US'` → `'(201) 555-0123'` |
| `isValidPhone(digits, country)` | Whether the digits after the calling code have a valid length |
| `toE164(digits, country)` | `'541234567'`, `'IL'` → `'+972541234567'` |

```ts
const { country, nationalNumber } = parsePhone(user.phone);
const shown = country ? formatNationalNumber(nationalNumber, country) : user.phone;
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | The number in E.164, `''` when empty. Leave it out to keep the number inside. |
| `defaultValue` | `string` | `''` | Starting number when `value` isn't set. |
| `onChange` | `(value: string, details: PhoneDetails) => void` | — | Called as the user types or picks a country. |
| `country` | `CountryCode` | — | The country whose calling code is used. |
| `defaultCountry` | `CountryCode` | `'US'` | Starting country when `country` isn't set. |
| `onCountryChange` | `(country: CountryCode) => void` | — | Called when the user picks a country or pastes a number from another. |
| `label` | `string` | — | Above the field, or on its border in Material. Screen readers hear *Phone number* without one. |
| `placeholder` | `string` | an example, e.g. `(123) 456-7890` | Shown while empty. |
| `disabled` | `boolean` | `false` | |
| `countries` / `exclude` / `preferred` | `CountryCode[]` | — | Which countries the list offers, and which come first. See [CountryPicker](./country-picker#a-subset-of-countries). |
| `preferredLabel` / `allCountriesLabel` | `string` | `'Suggested'` / `'All countries'` | Headers of the list. |
| `locale` | `string` | device locale | Language of the country names. |
| `presentation` | `'auto' \| 'dropdown' \| 'bottomSheet' \| 'modal'` | `'auto'` | Where the country list opens: a dropdown on the web, a bottom sheet on native. |
| `countrySheetTitle` | `string` | `'Country code'` | Title of the country sheet. |
| `sheet` | `SheetChromeProps` | `sheetProps.height: 0.8` | Options for the country sheet, as [`CountryPicker`](./country-picker#props)'s. |
| `theme` / `design` | | | See [Theming](../guides/theming) and [Designs](../guides/designs). |
| `style` | `ViewStyle` | — | The field's container. |
| `styles` | `{ label, field, input, countryButton, dialCode, chevron }` | — | [Slot styles](../guides/styling). |
| `testID` | `string` | — | On the text input; the country button gets `${testID}-country`. |

#### Types

```ts
interface PhoneDetails {
  country: CountryCode;
  nationalNumber: string; // digits after the calling code, e.g. '541234567'
  valid: boolean; // has as many digits as the country's numbers do
}
```

---

## 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 bottom sheet (a dropdown under the field on the web), and sees the value in the field once it closes. Each picker has a field that does this, with the same look as [`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` |
| `DurationPickerField` | [`DurationPickerSheet`](./duration-picker#in-a-sheet) | `1 h 30 min` |
| `MonthPickerField` | [`MonthPickerSheet`](./month-picker#in-a-sheet) | `October 2026` |
| `ColorPickerField` | [`ColorPickerSheet`](./color-picker#in-a-sheet) | A swatch and `#E4572E` |
| `WheelPickerField` | [`WheelPickerSheet`](./picker-sheets#wheelpickersheet) | The selected item's `label` |
| `EmojiPickerField` | [`EmojiPickerSheet`](./picker-sheets#emojipickersheet) | `value`, the emoji you pass |
| `PickerField` | Any sheet you render | `displayValue` |

```tsx
import { DatePickerField, TimePickerField, DateTimePickerField, WheelPickerField, EmojiPickerField, PickerField } from '@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. On the web they open as dropdowns; switch `presentation` in the panel to see the same form with bottom sheets or modals.

### Try the props

### Dropdown, bottom sheet or modal

`presentation` sets where the picker opens:

| `presentation` | Opens |
| --- | --- |
| `'auto'` (default) | A dropdown on the web, a bottom sheet on native. |
| `'dropdown'` | Under the field, like a menu, or above it when there's more room there. **Cancel** and **Done** sit below the picker; a tap outside cancels. It's at least 320 px wide, so a calendar fits under a narrow field. It opens on the side with room for the whole picker; in a window too short for it, the dropdown scrolls. |
| `'bottomSheet'` | A bottom sheet with the title and buttons in its header. |
| `'modal'` | A centered dialog. |

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

`sheetProps` and `title` apply to the bottom sheet and the modal; the dropdown has no header. [`SelectPicker`](./select-picker#presentation) takes the same values and the same `'auto'` default.

### What the field shows

Dates and times are formatted with `Intl` for the field's `locale` (the device locale by default). `TimePickerField` 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 (a bottom sheet or modal; the dropdown has no title).

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

### Clearing

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

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

### 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. A `PickerSheet` inside follows the field's `presentation`, so it opens as a dropdown on the web; a `presentation` set on the `PickerSheet` itself wins.

```tsx live
import { useState } from 'react';
import { 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`, `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. |
| `presentation` | `'auto' \| 'dropdown' \| 'bottomSheet' \| 'modal'` | `'auto'` | Where the picker opens: a dropdown on the web, a bottom sheet on native. See [Dropdown, bottom sheet or modal](#dropdown-bottom-sheet-or-modal). |
| `onOpen` / `onClose` | `() => void` | — | The picker 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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). Passed on to the sheet it opens. |
| `testID` | `string` | — | Test ID on the field box. |

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

#### Types

```ts
import type {
  DatePickerFieldProps,
  TimePickerFieldProps,
  DateTimePickerFieldProps,
  WheelPickerFieldProps,
  EmojiPickerFieldProps,
  PickerFieldProps,
  PickerFieldBaseProps,
  PickerFieldSlot,
  PickerFieldTriggerInfo,
  FieldPresentation,
  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 picker is open. The dropdown closes on a tap outside it and on the Android back button. 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 **Cancel / Done**: in the header beside the title on iOS, under the content with **OK** in Material, per the [design](../guides/designs). 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`, `DurationPickerField`, `MonthPickerField`, `ColorPickerField`, `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'` · `'OK'` Material | 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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |

---

### 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

### 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}
    />
  );
}
```

### Searching a server

`loadOptions` loads the options for what the user types, with the loader showing from the keystroke until they arrive. Here the list starts with recent picks and searches a fake API:

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

const RECENT = ['react', 'react-native', 'expo'].map((name) => ({ label: name, value: name, description: 'Recent' }));
const PACKAGES = ['react', 'react-dom', 'react-native', 'react-native-web', 'react-query', 'redux', 'expo', 'expo-router', 'zod', 'zustand', 'date-fns', 'dayjs'];

// Stands in for a package registry search
const searchPackages = (query: string) =>
  new Promise<{ label: string; value: string }[]>((resolve) =>
    setTimeout(() => resolve(PACKAGES.filter((p) => p.includes(query.toLowerCase())).map((p) => ({ label: p, value: p }))), 500)
  );

export default function Example() {
  const [packages, setPackages] = useState<string[]>([]);
  return (
    <SelectList
      multiple
      options={RECENT}
      loadOptions={searchPackages}
      value={packages}
      onChange={setPackages}
      searchPlaceholder="Search packages"
      loadingText="Searching the registry…"
      listHeight={300}
    />
  );
}
```

### Loading more as you scroll

`onEndReached` fires near the end of the list; append the next page to `options` and set `loading` while it's on its way. The spinner shows under the options.

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

const PAGE = 15;
const TOTAL = 60;

// Stands in for your API
const fetchPage = (offset: number) =>
  new Promise<{ label: string; value: number }[]>((resolve) =>
    setTimeout(
      () =>
        resolve(
          Array.from({ length: Math.min(PAGE, TOTAL - offset) }, (_, i) => ({
            label: `Contact ${offset + i + 1}`,
            value: offset + i + 1,
          }))
        ),
      800
    )
  );

export default function Example() {
  const [contact, setContact] = useState<number | null>(null);
  const [options, setOptions] = useState<{ label: string; value: number }[]>([]);
  const [loading, setLoading] = useState(false);

  const loadMore = () => {
    if (loading || options.length >= TOTAL) return;
    setLoading(true);
    fetchPage(options.length).then((page) => {
      setOptions((current) => [...current, ...page]);
      setLoading(false);
    });
  };

  useEffect(loadMore, []);

  return (
    <SelectList
      options={options}
      value={contact}
      onChange={setContact}
      searchable={false}
      loading={loading}
      loadingText="Loading contacts…"
      onEndReached={loadMore}
      listHeight={300}
    />
  );
}
```

### 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; with `onSearchChange`, that reset calls `onSearchChange('')` so a remote list can drop its results.
- For options from a server, see [Search on a server](./select-picker#search-on-a-server): `loadOptions`, `onSearchChange`, `loading` and `onEndReached` work the same here.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `ReadonlyArray<SelectOption<T>>` | `[]` | See [options](./select-picker#options). With `loadOptions`, the ones shown before the user types. |
| `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`; none with `loadOptions` / `onSearchChange` | Custom filter. |
| `loadOptions` | `(query: string) => Promise<SelectOption<T>[]>` | — | [Search a server](./select-picker#search-on-a-server): loader, debounce and stale answers handled. |
| `onSearchChange` | `(query: string) => void` | — | Called once typing pauses, to search yourself. |
| `searchPrompt` | `string` | `'Type to search'` | Shown before the user types, while a searched list has no options. |
| `searchDebounce` | `number` | `300` | ms after the last keystroke before `loadOptions` / `onSearchChange`. |
| `onEndReached` | `() => void` | — | Called near the end of the list, to load more. |
| `loading` | `boolean` | `false` | Spinner in place of an empty list, or under the options. |
| `loadingText` | `string` | `'Loading…'` | Text next to the spinner. |
| `renderLoading` | `(theme: PickerTheme) => ReactNode` | — | Custom loader. |
| `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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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, and the `searchPrompt` |
| `loading` / `loadingText` | Loader row / its text |

#### 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 searchable list: in a bottom sheet on phones, a dropdown under the field on the web, or a centered modal (`presentation`). Single or multiple selection, with groups, icons, descriptions, chips, a clear button and [search on your server](../recipes/server-search). It follows the [iOS, Material or web design](../guides/designs): a ✓ or radios, rounded or edge-to-edge rows.

```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

### 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()}
```

### Search on a server

Pass `loadOptions` and the picker runs the search for you. It waits for a pause in typing (`searchDebounce`, 300 ms by default), shows the loader from the keystroke until the results arrive, and ignores answers to older queries. Before the user types, it lists `options`; with none, like here, it shows `searchPrompt` (default *Type to search*). A search with no results shows `emptyText`.

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

const CITIES = ['Amsterdam', 'Athens', 'Barcelona', 'Berlin', 'Lisbon', 'London', 'Madrid', 'Milan', 'Paris', 'Prague', 'Rome', 'Vienna'];

// Stands in for your API
const searchCities = (query: string) =>
  new Promise<{ label: string; value: string }[]>((resolve) =>
    setTimeout(
      () =>
        resolve(
          CITIES.filter((c) => c.toLowerCase().includes(query.toLowerCase())).map((c) => ({
            label: c,
            value: c,
          }))
        ),
      700
    )
  );

export default function Example() {
  const [city, setCity] = useState<string | null>(null);
  return (
    <SelectPicker
      label="City"
      placeholder="Search a city"
      value={city}
      onChange={setCity}
      loadOptions={searchCities}
      searchPrompt="Type a city"
      emptyText="No city matches"
    />
  );
}
```

- **Search field from the start**, even with no `options`.
- **No double filtering**: results are listed as `loadOptions` returns them. Pass `filterOption` to filter anyway.
- **The selected label stays** in the field after a new search drops it from the results.
- **A failed request** shows `emptyText`.

For a whole form built this way, see the [flight search form recipe](../recipes/flight-search-form).

#### Searching yourself

For full control (pagination, caching, your own state), use `onSearchChange` instead: it's called with the query once typing pauses, and you set `options` and `loading`. With options showing, `loading` puts the spinner under them, which suits `onEndReached` for loading the next page. See the [Search a server recipe](../recipes/server-search).

`renderLoading` replaces the spinner and text with your own element:

```tsx
<SelectPicker
  // …
  loading={loading}
  renderLoading={(theme) => <Text style={{ color: theme.colors.textSecondary }}>Asking the server…</Text>}
/>
```

### 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<string | null>(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>>` | `[]` | The options; with `loadOptions`, the ones shown before the user types. |
| `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, or in a search field atop the list with `renderTrigger`. Sheet: show the search field. |
| `searchPlaceholder` | `string` | `'Search'` | Search hint. |
| `filterOption` | `(option, query) => boolean` | `defaultFilter`; none with `loadOptions` / `onSearchChange` | Custom search. |
| `loadOptions` | `(query: string) => Promise<SelectOption<T>[]>` | — | [Search a server](#search-on-a-server): loader, debounce and stale answers handled. An empty query shows `options`. |
| `onSearchChange` | `(query: string) => void` | — | Called once typing pauses, to [search yourself](#searching-yourself). |
| `searchPrompt` | `string` | `'Type to search'` | Shown before the user types, while a searched list has no options. |
| `searchDebounce` | `number` | `300` | ms after the last keystroke before `loadOptions` / `onSearchChange`. |
| `onEndReached` | `() => void` | — | Called near the end of the list, to load more. |
| `loading` | `boolean` | `false` | Spinner in place of an empty list, or under the options. |
| `loadingText` | `string` | `'Loading…'` | Text next to the spinner. |
| `renderLoading` | `(theme) => ReactNode` | — | Custom loader. |
| `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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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
- [`CountryPicker`](./country-picker): this field with about 250 countries built in, and the [country and phone number recipe](../recipes/country-select)
- [Tag picker recipe](../recipes/tags)
- [Search a server recipe](../recipes/server-search): loading, debounced search and load-more
- [Flight search form recipe](../recipes/flight-search-form): a full form with airports searched on a server

---

## React Native Time Picker

## TimePicker

`TimePicker` is a React Native time picker for hours, minutes and optionally seconds and AM/PM. It looks native on each platform: [wheels on iOS, a Material clock dial on Android, columns to click on the web](#wheels-a-dial-or-a-list), or the one you pick with `display`. The 12h or 24h clock and the AM/PM labels come from the locale automatically.

Picking a length of time, such as a timer or a workout, rather than a time of day? Use [`DurationPicker`](./duration-picker).

```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"
      />
    </>
  );
}
```

### Wheels, a dial or a list

Each [design](../guides/designs) has its own default:

| `display` | Default in | What it is |
| --- | --- | --- |
| `'wheel'` | iOS | Hour, minute and AM/PM wheels |
| `'dial'` | Material | The time in large type above a clock dial. Tap or drag to the hour, lift, then the minutes; tap the hours or minutes above to switch. 24h dials have 1–12 outside and 00, 13–23 on an inner ring. The keyboard button under the dial switches to typing the hours and minutes |
| `'input'` | | Material's time input: the hour and minute fields to type into, without the dial. Compact, so `DateTimePicker` uses it under a Material calendar |
| `'list'` | web | Hours, minutes (and seconds) and AM/PM side by side in a bordered panel, each a column of cells to click, the chosen one kept at the top |

```tsx
<TimePicker value={time} onChange={setTime} display="dial" minuteInterval={5} />
```

A dial or time input has no seconds, so with `showSeconds` they show wheels instead. Screen readers adjust the dial up and down by an hour, or by `minuteInterval`.

### 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`). Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

| 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'`. |
| `display` | `'wheel' \| 'dial' \| 'input' \| 'list'` | from the design | Wheels (iOS), a clock dial (Material), typed fields, or columns to click (web). |
| `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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID. |

### Related

- [Alarm recipe](../recipes/alarm-time)
- [TimePickerField](./picker-fields): the picker behind a form field
- [DurationPicker](./duration-picker): for a length of time rather than a time of day

---

## React Native Time Zone Picker

## TimeZonePicker

`TimeZonePicker` is a React Native form field for choosing a time zone: all 418 IANA zones, each with its city, its offset from GMT and, where the JavaScript engine has it, its name, such as *Central European Summer Time*. The list is sorted by offset, with the device's own zone on top. It's a [`SelectPicker`](./select-picker) with the list built in, so it takes the same props: a bottom sheet on phones, a dropdown on the web, multiple selection, a clear button and the [iOS, Material or web design](../guides/designs).

The value is the IANA name, such as `'Europe/Lisbon'`, ready to store or pass to `Intl.DateTimeFormat`.

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

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

export default function Example() {
  const [timeZone, setTimeZone] = useState<string | null>('Europe/Lisbon');
  return <TimeZonePicker label="Time zone" value={timeZone} onChange={setTimeZone} />;
}
```

Try searching `tokyo`, `utc+5:30`, `pacific` or `America/New_York`.

### Try the props

### Offsets and daylight saving

Offsets are worked out for the current moment, so a zone with daylight saving shows its summer offset in summer and its winter one in winter. To show them for another moment, such as the date of a meeting being scheduled, pass `date`.

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

const MEETING = new Date(2027, 0, 15, 15, 0);

export default function Example() {
  const [timeZone, setTimeZone] = useState<string | null>(null);
  return <TimeZonePicker label="Meeting time zone" date={MEETING} value={timeZone} onChange={setTimeZone} />;
}
```

### The device's zone and preferred zones

The device's zone is shown first, under *Your time zone*. Pass `preferred` to pin others instead, in the order you give, or an empty array to pin none. `timeZones` limits the list to the zones you support.

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

const OFFICES = ['America/New_York', 'Europe/London', 'Asia/Singapore'];

export default function Example() {
  const [timeZone, setTimeZone] = useState<string | null>(null);
  return (
    <TimeZonePicker label="Office" preferred={OFFICES} preferredLabel="Our offices" value={timeZone} onChange={setTimeZone} />
  );
}
```

### Old and new zone names

Some zones were renamed: `Asia/Calcutta` is now `Asia/Kolkata`, `Europe/Kiev` is `Europe/Kyiv`. Phones report the new names, while some browsers still report the old ones. The picker accepts either as `value` and always reports the new one, so a value saved on one device shows on another. [`normalizeTimeZone`](#utilities) does the same for your own data.

### On Hermes

Hermes, React Native's default engine, can't list time zones, so the list ships with the library (8 KB, read on first use). Offsets come from `Intl.DateTimeFormat`, which Hermes has. Zone names such as *India Standard Time* show where the engine provides them; where it doesn't, each zone shows its region instead, as *GMT+5:30 · Asia*.

### Utilities

| Export | Description |
| --- | --- |
| `getDeviceTimeZone()` | The device's zone, e.g. `'Europe/Lisbon'`, or `undefined` |
| `getTimeZoneOffset(id, date?)` | Minutes ahead of UTC at `date` (default: now), e.g. `330` for `'Asia/Kolkata'` |
| `formatGmtOffset(minutes)` | `330` → `'GMT+5:30'`, `0` → `'GMT'` |
| `getTimeZoneName(id, locale?, date?)` | `'Central European Summer Time'`, where the engine has names |
| `normalizeTimeZone(id)` | `'Asia/Calcutta'` → `'Asia/Kolkata'` |
| `getTimeZone(id)` | `{ id, alias?, city, region }` |
| `getAllTimeZones()` | Every zone, sorted by name |

```ts
const zone = getDeviceTimeZone() ?? 'UTC';
const label = `${getTimeZone(zone)?.city} (${formatGmtOffset(getTimeZoneOffset(zone) ?? 0)})`; // 'Lisbon (GMT+1)'
```

### Props

Every [`SelectPicker` prop](./select-picker#props) works, apart from the server search ones (`options`, `loadOptions`, `onSearchChange`, `loading` and the rest): the list is built in. `value` is an IANA name, or an array of them with `multiple`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeZones` | `string[]` | all | Only these zones. |
| `preferred` | `string[]` | the device's zone | Shown first, in this order, under their own header. `[]` pins none. |
| `preferredLabel` | `string` | `'Your time zone'` | Header above `preferred`. |
| `allTimeZonesLabel` | `string` | `'All time zones'` | Header above the rest. |
| `date` | `Date` | now | The moment offsets are worked out for. |
| `locale` | `string` | device locale | Language of the zone names, where the engine has them. |
| `placeholder` | `string` | `'Select a time zone'` | Shown while nothing is selected. |
| `searchPlaceholder` | `string` | `'Search time zones'` | Search field placeholder. |
| `sheet` | `SheetChromeProps` | `sheetProps.height: 0.8` | Sheet options. The sheet opens at 80% of the screen so it doesn't jump as search narrows the list. |

---

## React Native Week Strip

## WeekStrip

`WeekStrip` is one week of days in a row, the compact date picker at the top of booking, schedule, habit and fitness screens. Tap a day to pick it; swipe or use the arrows for the next or previous week. The month and year most of the week falls in sit above it.

It's the [`Calendar`](./date-picker)'s day cells in a single week, so it follows the [design](../guides/designs) the same way and takes the same `markedDates`, `minDate`, `maxDate`, `isDateDisabled`, `renderDay` and styles.

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

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

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

### Try the props

### Marked and disabled days

`markedDates` adds dots, a label or a disabled flag to days, keyed by `YYYY-MM-DD` ([`toDateKey`](../api/date-utils#todatekey)), as on the calendar. `minDate`, `maxDate` and `isDateDisabled` disable days, and the arrows stop at the weeks holding `minDate` and `maxDate`.

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

const today = new Date();
const CLASSES = {
  [toDateKey(today)]: { dots: ['#E4572E'] },
  [toDateKey(addDays(today, 2))]: { dots: ['#E4572E', '#2E86AB'] },
  [toDateKey(addDays(today, 4))]: { dots: ['#2E86AB'] },
};

export default function Schedule() {
  const [day, setDay] = useState(today);
  return (
    <WeekStrip
      value={day}
      onChange={setDay}
      markedDates={CLASSES}
      minDate={today}
      isDateDisabled={(date) => date.getDay() === 0}
    />
  );
}
```

### Weeks

The first day of the week comes from `locale` (Sunday in the US, Monday in most of Europe), or set `firstDayOfWeek`: `0` for Sunday to `6` for Saturday. The strip opens on the week of `value`, or of today, or of `initialWeek`, and moves to a new `value`'s week when you set one from outside.

`onWeekChange` fires with the first day of the week after an arrow or a swipe, to load that week's data:

```tsx
<WeekStrip value={day} onChange={setDay} markedDates={marks} onWeekChange={(start) => loadWeek(start)} />
```

`showHeader={false}` hides the title and arrows, leaving the days and the swipe. `formatTitle(weekStart, locale)` changes the title.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date \| null` | — | Selected day (controlled). |
| `defaultValue` | `Date \| null` | — | Initial day when uncontrolled. |
| `onChange` | `(date: Date) => void` | — | Fires when a day is tapped. |
| `initialWeek` | `Date` | the selected day or today | A day in the week shown first. |
| `onWeekChange` | `(weekStart: Date) => void` | — | Fires with the first day of the week after paging. |
| `firstDayOfWeek` | `0`–`6` | from `locale`, else `0` | `0` = Sunday. |
| `locale` | `string` | device | Weekday and month names. |
| `minDate` / `maxDate` | `Date` | — | Days outside are disabled, and paging stops at their weeks. |
| `isDateDisabled` | `(date: Date) => boolean` | — | Disable a day. |
| `markedDates` | `Record<string, MarkedDate>` | — | Dots, labels or disabled days, keyed by `YYYY-MM-DD`. |
| `showHeader` | `boolean` | `true` | Show the month title and the week arrows. |
| `formatTitle` | `(weekStart: Date, locale?: string) => string` | the month of the week's middle day | Title text. |
| `showWeekdays` | `boolean` | `true` | Show the weekday names. |
| `weekdayFormat` | `'short' \| 'narrow'` | from the design | Weekday names: `Mon` or `M`. |
| `enableSwipe` | `boolean` | `true` | Swipe left or right to change weeks. |
| `renderDay` | `(state: DayState, theme: PickerTheme) => ReactNode` | — | Fully custom day cell, as on the [calendar](./date-picker#custom-days-and-arrows). |
| `renderArrow` | `(direction, disabled) => ReactNode` | — | Custom arrows. |
| `dayHeight` | `number` | `44` | Day cell height. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<CalendarSlot>` | — | The [calendar slots](./date-picker#slots). |
| `theme` | `DeepPartial<PickerTheme>` | — | Theme override. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `testID` | `string` | — | Test ID. |

### Related

- [DatePicker](./date-picker): a whole month
- [MonthPicker](./month-picker): a month and year

---

## 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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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 noplatforms
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`. Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

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

### Props

| 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. |
| `design` | `'ios' \| 'material' \| 'web'` | from `PickersProvider` | The look to follow, over the provider's: [iOS, Material or web](../guides/designs). |
| `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,923 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 |
| [`DurationPicker`](../components/duration-picker) | A length of time in seconds: wheels, number boxes or columns |
| [`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 |
| [`MonthPicker`](../components/month-picker) | Month and year: wheels (iOS) or a grid of months (Material, web) |
| [`WeekStrip`](../components/week-strip) | One week of days in a row, swipe or arrows to page |
| [`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 |
| [`CountryPicker`](../components/country-picker) | Country field: flags, dialing codes, localized names |
| [`PhoneField`](../components/phone-field) | Phone number input: country code button, formats as you type, E.164 value |
| [`TimeZonePicker`](../components/time-zone-picker) | Time zone field: GMT offsets, sorted by offset, the device's zone on top |
| [`HorizontalList<T>`](../components/horizontal-list) | Segmented control or chips that scroll sideways |
| [`EmojiPicker`](../components/emoji-picker) | Emoji keyboard |
| [`ColorPicker`](../components/color-picker) | iOS's tabs, Google's swatch circles or the browser's spectrum; hex with opacity |
| [`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 |
| [`DurationPickerSheet`](../components/duration-picker#in-a-sheet) | DurationPicker in a sheet |
| [`MonthPickerSheet`](../components/month-picker#in-a-sheet) | MonthPicker in a sheet |
| [`WheelPickerSheet<T>`](../components/picker-sheets#wheelpickersheet) | WheelPicker in a sheet |
| [`EmojiPickerSheet`](../components/picker-sheets#emojipickersheet) | EmojiPicker in a sheet |
| [`ColorPickerSheet`](../components/color-picker#in-a-sheet) | ColorPicker 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 |
| [`DurationPickerField`](../components/duration-picker#in-a-form-field) | Field + DurationPickerSheet; shows `1 h 30 min` |
| [`MonthPickerField`](../components/month-picker#in-a-form-field) | Field + MonthPickerSheet; shows `October 2026` |
| [`WheelPickerField<T>`](../components/picker-fields) | Field + WheelPickerSheet; shows the item's label |
| [`EmojiPickerField`](../components/picker-fields) | Field + EmojiPickerSheet; shows `value` |
| [`ColorPickerField`](../components/color-picker#in-a-form-field) | Field + ColorPickerSheet; shows a swatch and the hex code |

### Theme

| Export | Description |
| --- | --- |
| [`PickersProvider`](../guides/theming#pickersprovider) | App-wide theme, colour scheme, platform and design |
| [`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 |
| [`DESIGN`](./theme#designs) / [`DESIGN_TOKENS`](./theme#designs) / [`resolveDesign(preference, platform)`](./theme#designs) | The iOS, Material and web designs |
| [`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)

### Color utilities

[`normalizeHex`](../components/color-picker#utilities) · [`hexToHsv`](../components/color-picker#utilities) · [`hsvToHex`](../components/color-picker#utilities) · [`withAlpha`](../components/color-picker#utilities) · [`DEFAULT_COLORS`](../components/color-picker#utilities)

### Country utilities

[`getCountry`](../components/country-picker#utilities) · [`getAllCountries`](../components/country-picker#utilities) · [`getCountryFlag`](../components/country-picker#utilities)

### Phone utilities

[`parsePhone`](../components/phone-field#utilities) · [`formatNationalNumber`](../components/phone-field#utilities) · [`isValidPhone`](../components/phone-field#utilities) · [`toE164`](../components/phone-field#utilities)

### Time zone utilities

[`getDeviceTimeZone`](../components/time-zone-picker#utilities) · [`getTimeZoneOffset`](../components/time-zone-picker#utilities) · [`formatGmtOffset`](../components/time-zone-picker#utilities) · [`getTimeZoneName`](../components/time-zone-picker#utilities) · [`normalizeTimeZone`](../components/time-zone-picker#utilities) · [`getTimeZone`](../components/time-zone-picker#utilities) · [`getAllTimeZones`](../components/time-zone-picker#utilities)

### Duration utilities

[`formatDuration(seconds, { showHours?, labels? })`](../components/duration-picker#formatduration): `5400` → `'1 h 30 min'`

### 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';

/** A field's `presentation`: a sheet presentation, or a dropdown under the field. Its `auto` (the default) is a dropdown on the web. */
type FieldPresentation = SheetPresentation | 'dropdown';

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

/** 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` (iOS, web) · `OK` (Material) / `Cancel` |
| SelectPicker, fields | `placeholder` | `Select…` |
| SelectList | `searchPlaceholder` / `emptyText` / `loadingText` / `searchPrompt` | `Search` / `No results` / `Loading…` / `Type to search` |
| CountryPicker | `placeholder` / `searchPlaceholder` / `preferredLabel` / `allCountriesLabel` | `Select a country` / `Search countries` / `Suggested` / `All countries` |
| PhoneField | `label` / `countrySheetTitle` | none (read as `Phone number`) / `Country code` |
| TimeZonePicker | `placeholder` / `searchPlaceholder` / `preferredLabel` / `allTimeZonesLabel` | `Select a time zone` / `Search time zones` / `Your time zone` / `All time zones` |
| EmojiPicker | `searchPlaceholder` / `emptyText` | `Search emoji` / `No emoji found` |
| TimePicker | `dayPeriodLabels` | from locale (`AM` / `PM`) |
| ColorPicker | `labels` | `Grid`, `Spectrum`, `Sliders`, `Hue`, `Opacity`, `Red`, `Green`, `Blue`, `Hex`, `Copy`, `Copied`, `Custom colour`… |
| DurationPicker | `labels` | `{ hours: 'h', minutes: 'min', seconds: 's' }` |

### 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, DurationPicker, DateWheelPicker, MonthPicker | wheels |
| `keyboardInput` | `true` | WheelPicker |
| `minuteInterval` / `secondInterval` | `1` | TimePicker, DurationPicker |
| `format` | `'auto'` | TimePicker |
| `display` | `'wheel'` iOS · `'dial'` Material · `'list'` web | TimePicker |
| `display` | `'wheel'` iOS · `'input'` Material · `'list'` web | DurationPicker |
| `display` | `'wheel'` iOS · `'grid'` Material, web | MonthPicker |
| `display` | `'tabs'` iOS · `'swatches'` Material · `'spectrum'` web | ColorPicker |
| `display` / `timeDisplay` | `'wheel'` / `'wheel'` iOS · `'calendar'` / `'input'` Material · `'calendar'` / `'list'` web | DateTimePicker |
| `timePosition` | `'beside'` web · `'below'` other | DateTimePicker |
| `dayHeight` | `44` | Calendar |
| `fixedWeeks` / `showOutsideDays` | `true` | Calendar |
| `enableSwipe` / `enableQuickJump` | `true` | Calendar |
| `weekdayFormat` | `'short'` · `'narrow'` Material | Calendar |
| `monthFormat` | `'long'` | DateWheelPicker, MonthPicker |
| `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
  platform?: PlatformOSType;               // default Platform.OS
  design?: 'auto' | 'ios' | 'material' | 'web'; // default 'auto'
}): JSX.Element;
```

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

### `usePickerTheme`

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

Returns the active theme: the design's tokens on the built-in light or dark theme, then the provider's overrides, then `override`. The design comes from `override.design`, the provider's `design`, or the platform. `theme.design` tells your own components which design to match.

### `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).

### Designs

```ts
const DESIGN: { auto: 'auto'; ios: 'ios'; material: 'material'; web: 'web' };
const DESIGN_TOKENS: Record<Design, DeepPartial<PickerTheme>>; // what each design changes on the light or dark theme
function resolveDesign(preference: DesignPreference, platform: PlatformOSType): Design;
```

`resolveDesign('auto', platform)` gives `'ios'` on iOS, `'web'` on the web and `'material'` everywhere else. See [designs](../guides/designs).

### `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>; design?: Design }
type DesignPreference = 'auto' | 'ios' | 'material' | 'web';
type Design = 'ios' | 'material' | 'web';
```

---

## Accessibility

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

### 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`.
- While `loading`, the loader is a `progressbar`.

### Horizontal list

The list is a `radiogroup` named by `accessibilityLabel`; each item is a `radio` labelled with its `label`, with `checked` and `disabled` states.

### 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.

### Keyboard

On the web, every picker works without a mouse:

| Key | What it does |
| --- | --- |
| <kbd>Tab</kbd> | Moves between fields, buttons, wheels and sliders |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Opens a field, picks the focused day, option or emoji |
| <kbd>↑</kbd> <kbd>↓</kbd> | On a wheel, steps one row. In a calendar, list or grid, moves to the cell above or below. From a search field, goes into the results, and back |
| <kbd>←</kbd> <kbd>→</kbd> | Moves to the next cell, wrapping to the next row, or to the next wheel of a date or time |
| <kbd>Home</kbd> / <kbd>End</kbd> | Jumps to the first or last cell, or to the ends of a wheel or slider |
| <kbd>Esc</kbd> | Closes a sheet or dropdown |

Arrows follow what's drawn, so they go the right way in RTL and in any custom layout. Colour sliders and the colour square move with the arrows, and the clock dial steps its hand. When a sheet or dropdown closes, focus goes back to the field that opened it.

### 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`, `DurationPickerField`, `MonthPickerField`, `ColorPickerField`, `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.

#### Options from your API

A field whose options come from a server takes `loadOptions` instead of a fixed list. It searches as the user types, with a loader, and the form only ever sees the picked value:

```tsx
<Controller
  control={control}
  name="assignee"
  rules={{ required: 'Assign someone' }}
  render={({ field }) => (
    <SelectPicker
      label="Assignee"
      placeholder="Search people"
      loadOptions={(query) => api.searchUsers(query).then((users) => users.map((u) => ({ label: u.name, value: u.id })))}
      value={field.value}
      onChange={field.onChange}
      onClose={field.onBlur}
    />
  )}
/>
```

The field keeps showing the picked person's name after later searches stop returning them. For a full form with server search, see the [flight search form recipe](../recipes/flight-search-form).

#### 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.

Hermes can't list or name countries and time zones (`Intl.DisplayNames`, `Intl.supportedValuesOf`), so [`CountryPicker`](../components/country-picker) and [`TimeZonePicker`](../components/time-zone-picker) ship their lists. Names show in the user's language where the engine provides them, and in English otherwise.

### Translating UI strings

| Component | String props (defaults) |
| --- | --- |
| Picker sheets | `confirmLabel` (`Done`, `OK` in Material), `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]`) |
| `DurationPicker` | `labels` (`h`, `min`, `s`) |
| `ColorPicker` | `labels`: tab, slider and button names (`Grid`, `Hue`, `Opacity`, `Copy`…) |
| `Calendar`, `WeekStrip` | `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,923-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 zero native code matters

- **Native feel, your brand.** Each platform gets its own [design](./designs), in your colors and fonts. Native date pickers change with every OS version, and Android's calendar dialog can't be themed much.
- **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.

### Designs

Pickers look native on each platform: iOS on iOS, Material Design on Android, a web design on the web. Set `design="ios"` (or `"material"`, `"web"`) on `PickersProvider` to use one look everywhere. See [Designs](./designs) for what each one changes and how to customize it.

### 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.
- Everything works from the keyboard: arrow keys move through calendars, lists and grids and step wheels and sliders, <kbd>Esc</kbd> closes a sheet, and focus returns to the field. See [Accessibility](./accessibility.mdx#keyboard).
- Animations run on the JS driver on the web, because the native driver isn't available there.

#### Previewing other platforms

Pickers adapt to `Platform.OS`: fields open a dropdown on the web and a bottom sheet on iOS and Android, sheets keep room for the iOS home indicator and status bar, and headers drag on native. To see the native behavior in a browser (a design system, Storybook, these docs), set `platform` on the provider:

```tsx
<PickersProvider platform="ios">
  <App />
</PickersProvider>
```

The switch on every live example here previews iOS, Android and Web this way, with each platform's [design](./designs). Other platforms, such as Windows and macOS, behave like Android.

#### 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` |
| `SelectPicker` / `SelectList` | `renderLoading` | `(theme) => ReactNode` |
| `HorizontalList` | `renderItem` | `({ item, selected, disabled, 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 / DurationPicker](../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` |
| [MonthPicker](../components/month-picker#props) | the wheel slots, or the grid's `header` `headerTitle` `arrow` `arrowText` `gridCell` `gridCellText` |
| [WeekStrip](../components/week-strip#props) | the Calendar slots |
| [ColorPicker](../components/color-picker#props) | `container` `swatch` `pad` `slider` `sliderThumb` `sliderLabel` `hexInput` `preview` |
| [SelectList](../components/select-list#slots) | `container` `search` `searchInput` `list` `groupHeader` `groupHeaderText` `option` `selectedOption` `optionLabel` `selectedOptionLabel` `optionDescription` `check` `empty` `emptyText` `loading` `loadingText` |
| [SelectPicker](../components/select-picker#slots) | all SelectList slots + `trigger` `triggerText` `placeholder` `label` `chip` `chipText` `chevron` `clear` |
| [HorizontalList](../components/horizontal-list#slots) | `container` `content` `item` `selectedItem` `itemLabel` `selectedItemLabel` `thumb` `arrow` `arrowText` |
| [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`. |
| `platform` | `'ios' \| 'android' \| 'web' \| …` | `Platform.OS` | Pickers behave as on this platform. See [previewing other platforms](./platforms#previewing-other-platforms). |
| `design` | `'auto' \| 'ios' \| 'material' \| 'web'` | `'auto'` | The look pickers follow. `'auto'` matches the platform. See [designs](./designs). |
| `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;
  design: 'ios' | 'material' | 'web'; // see the Designs guide
  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,
  WeekStripProps, DurationPickerProps, DurationLabels, MonthPickerProps, MonthPickerSlot, MonthDisplay,
  // color
  ColorPickerProps, ColorPickerSlot, ColorOption, ColorDisplay, ColorLabels,
  // select
  SelectPickerProps, SelectListProps, SelectListBaseProps, SelectValueProps,
  SelectOption, SelectSlot, SelectTriggerSlot, SelectTriggerInfo, SelectRenderOptionInfo,
  // horizontal list
  HorizontalListProps, HorizontalListItem, HorizontalListIconInfo, HorizontalListIconPosition, HorizontalListVariant,
  HorizontalListArrowPosition, HorizontalListArrowSide,
  HorizontalListSlot, HorizontalListRenderItemInfo,
  // emoji
  EmojiPickerProps, EmojiPickerSlot, Emoji, EmojiCategory, SkinTone,
  // sheets
  BottomSheetProps, BottomSheetSlot, SheetChromeProps, SheetPresentation, SelectPresentation, PickerSheetProps,
  DatePickerSheetProps, TimePickerSheetProps, DateTimePickerSheetProps, WheelPickerSheetProps, EmojiPickerSheetProps,
  DurationPickerSheetProps, MonthPickerSheetProps, ColorPickerSheetProps,
  // fields
  PickerFieldProps, PickerFieldBaseProps, PickerFieldSlot, PickerFieldTriggerInfo, ChevronInfo, WithPickerField,
  DatePickerFieldProps, TimePickerFieldProps, DateTimePickerFieldProps, WheelPickerFieldProps, EmojiPickerFieldProps,
  DurationPickerFieldProps, MonthPickerFieldProps, ColorPickerFieldProps,
} 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 opens the picker and formats the time. The picker follows the [design](../guides/designs): wheels on iOS, Material's clock dial on Android, and time columns in a dropdown on the web.

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

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

export default function Alarm() {
  const { colors } = usePickerTheme();
  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, { color: colors.text }]}>{displayValue}</Text>
          </Pressable>
        )}
      />
      <Text style={[styles.caption, { color: colors.textSecondary }]}>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',
    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 enforces a minimum age of 13 and shows the age. It opens a calendar styled for each [design](../guides/designs), in a bottom sheet on phones and a dropdown on the web; `display="wheel"` switches to date wheels.

```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"
      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

- In the calendar, tap the month title to jump to a year instead of paging back month by month. Some apps prefer `display="wheel"` for birthdays, since a year wheel reaches decades back in one flick.
- `value` opens the picker 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 and years on the wheels) and clamps the value, so under-13 dates can't be confirmed.
- With wheels, the 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,
  usePickerTheme,
} 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 { colors } = usePickerTheme();
  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, { color: colors.textSecondary }]}>
          {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, { color: colors.primary }]}>
          {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' },
  total: { fontSize: 15, fontWeight: '700' },
});
```

### 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

On phones, open the calendar from a summary bar. The confirm button (**Done**, or **OK** in Material) stays disabled until both dates are chosen, and in Material the headline above the calendar shows the range as it's picked:

```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 }}
/>
```

---

## Category filter chips

A row of category chips above a menu, like a food or shop app. There are more categories than fit, so the row scrolls; tap the last visible chip and the next one slides into view, so people find the rest without guessing.

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

const CATEGORIES = [
  { label: 'All', value: 'all', icon: <Text>🍽️</Text> },
  { label: 'Breakfast', value: 'breakfast', icon: <Text>🥐</Text> },
  { label: 'Salads', value: 'salads', icon: <Text>🥗</Text> },
  { label: 'Pizza', value: 'pizza', icon: <Text>🍕</Text> },
  { label: 'Burgers', value: 'burgers', icon: <Text>🍔</Text> },
  { label: 'Sushi', value: 'sushi', icon: <Text>🍣</Text> },
  { label: 'Desserts', value: 'desserts', icon: <Text>🍰</Text> },
  { label: 'Drinks', value: 'drinks', icon: <Text>🥤</Text> },
];

const MENU = [
  { name: 'Croissant', category: 'breakfast', price: 4 },
  { name: 'Shakshuka', category: 'breakfast', price: 12 },
  { name: 'Greek salad', category: 'salads', price: 11 },
  { name: 'Margherita', category: 'pizza', price: 14 },
  { name: 'Smash burger', category: 'burgers', price: 15 },
  { name: 'Salmon roll', category: 'sushi', price: 13 },
  { name: 'Cheesecake', category: 'desserts', price: 8 },
  { name: 'Lemonade', category: 'drinks', price: 5 },
];

export default function Example() {
  const { colors } = usePickerTheme();
  const [category, setCategory] = useState('all');
  const dishes = category === 'all' ? MENU : MENU.filter((d) => d.category === category);
  return (
    <View style={styles.screen}>
      <HorizontalList
        variant="chips"
        items={CATEGORIES}
        value={category}
        onChange={setCategory}
        accessibilityLabel="Categories"
      />
      {dishes.map((dish) => (
        <View key={dish.name} style={[styles.row, { borderColor: colors.border }]}>
          <Text style={[styles.dish, { color: colors.text }]}>{dish.name}</Text>
          <Text style={[styles.dish, { color: colors.textSecondary }]}>${dish.price}</Text>
        </View>
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { gap: 4 },
  row: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    paddingVertical: 10,
    paddingHorizontal: 4,
    borderBottomWidth: StyleSheet.hairlineWidth,
  },
  dish: { fontSize: 15 },
});
```

### How it works

- `variant="chips"` shows separate pills; leave it out for a segmented control (good for 2–5 options like a sort order). Both follow the [design](../guides/designs): filled on iOS and the web, outlined with a ✓ on the chosen chip in Material.
- Each item's `icon` sits before its label. For anything else, render the whole item with `renderItem`.
- The list is controlled: keep the category in state and filter with it.
- Tapping a chip whose neighbor is cut off scrolls that neighbor into view, plus a peek of the one after it.

---

## Chat input with emoji

A chat screen with message bubbles, a composer with an emoji button next to **Send** that opens the emojis in a bottom sheet, emojis inserted **at the cursor** (not just appended), and a send button. Switch between the iPhone, Pixel and browser above it; the colours come from `usePickerTheme()`, so it follows dark mode and your theme.

```tsx live device
import { useRef, useState } from 'react';
import type { ComponentRef } from 'react';
import { Pressable, ScrollView, StyleSheet, Text, TextInput, View } from 'react-native';
import { EmojiPickerSheet, usePickerTheme } from '@elik56a/react-native-pickers';
import type { SkinTone } from '@elik56a/react-native-pickers';

type Message = { id: number; text: string; mine: boolean; time: string };

const FIRST: Message[] = [
  { id: 1, text: 'Are we still on for tonight? 🍕', mine: false, time: '6:02 PM' },
  { id: 2, text: 'Yes! 8 at the usual place', mine: true, time: '6:04 PM' },
  { id: 3, text: "Perfect, I'll book a table 🙌", mine: false, time: '6:05 PM' },
];

const timeNow = () => new Date().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });

export default function Chat() {
  const { colors, radius } = usePickerTheme();
  const [messages, setMessages] = useState(FIRST);
  const [text, setText] = useState('');
  const [showEmoji, setShowEmoji] = useState(false);
  const [tone, setTone] = useState<SkinTone>(0);
  const [recent, setRecent] = useState<string[]>(['😂', '❤️', '👍']);
  const selection = useRef({ start: 0, end: 0 });
  const list = useRef<ComponentRef<typeof ScrollView>>(null);
  const canSend = text.trim().length > 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 };
  };

  const send = () => {
    setMessages((m) => [...m, { id: Date.now(), text: text.trim(), mine: true, time: timeNow() }]);
    setText('');
    selection.current = { start: 0, end: 0 };
  };

  return (
    <View style={[styles.screen, { backgroundColor: colors.background }]}>
      <View style={[styles.header, { borderColor: colors.border }]}>
        <View style={[styles.avatar, { backgroundColor: colors.primaryMuted }]}>
          <Text style={styles.avatarText}>🧑‍🍳</Text>
        </View>
        <View>
          <Text style={[styles.name, { color: colors.text }]}>Maya</Text>
          <Text style={[styles.status, { color: colors.textSecondary }]}>online</Text>
        </View>
      </View>

      <ScrollView
        ref={list}
        style={styles.messages}
        contentContainerStyle={styles.messagesContent}
        onContentSizeChange={() => list.current?.scrollToEnd()}
      >
        {messages.map((m) => (
          <View
            key={m.id}
            style={[
              styles.bubble,
              m.mine ? styles.mine : styles.theirs,
              { borderRadius: radius.lg, backgroundColor: m.mine ? colors.primary : colors.surface },
            ]}
          >
            <Text style={[styles.text, { color: m.mine ? colors.onPrimary : colors.text }]}>{m.text}</Text>
            <Text style={[styles.time, { color: m.mine ? colors.onPrimary : colors.textSecondary }]}>{m.time}</Text>
          </View>
        ))}
      </ScrollView>

      <View style={[styles.composer, { borderColor: colors.border }]}>
        <TextInput
          value={text}
          onChangeText={setText}
          onSelectionChange={(e) => (selection.current = e.nativeEvent.selection)}
          onSubmitEditing={() => canSend && send()}
          placeholder="Message"
          placeholderTextColor={colors.textSecondary}
          style={[styles.input, { backgroundColor: colors.surface, color: colors.text }]}
        />
        <Pressable
          onPress={() => setShowEmoji(true)}
          accessibilityRole="button"
          accessibilityLabel="Emoji"
          style={styles.iconButton}
        >
          <Text style={styles.iconText}>😊</Text>
        </Pressable>
        <Pressable
          onPress={send}
          disabled={!canSend}
          accessibilityRole="button"
          accessibilityLabel="Send"
          style={[styles.send, { backgroundColor: canSend ? colors.primary : colors.surface }]}
        >
          <Text style={[styles.sendText, { color: canSend ? colors.onPrimary : colors.textDisabled }]}>↑</Text>
        </Pressable>
      </View>

      <EmojiPickerSheet
        visible={showEmoji}
        onClose={() => setShowEmoji(false)}
        onSelect={insert}
        skinTone={tone}
        onSkinToneChange={setTone}
        recent={recent}
        onRecentChange={setRecent}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1 },
  header: {
    flexDirection: 'row',
    alignItems: 'center',
    gap: 10,
    paddingHorizontal: 14,
    paddingVertical: 10,
    borderBottomWidth: StyleSheet.hairlineWidth,
  },
  avatar: { width: 36, height: 36, borderRadius: 18, alignItems: 'center', justifyContent: 'center' },
  avatarText: { fontSize: 20 },
  name: { fontSize: 16, fontWeight: '600' },
  status: { fontSize: 12 },
  messages: { flex: 1 },
  messagesContent: { padding: 12, gap: 6 },
  bubble: { maxWidth: '78%', paddingHorizontal: 12, paddingVertical: 8 },
  mine: { alignSelf: 'flex-end' },
  theirs: { alignSelf: 'flex-start' },
  text: { fontSize: 15, lineHeight: 20 },
  time: { fontSize: 11, opacity: 0.7, alignSelf: 'flex-end', marginTop: 2 },
  composer: {
    flexDirection: 'row',
    alignItems: 'center',
    gap: 6,
    paddingHorizontal: 10,
    paddingVertical: 8,
    borderTopWidth: StyleSheet.hairlineWidth,
  },
  iconButton: { width: 36, height: 36, alignItems: 'center', justifyContent: 'center' },
  iconText: { fontSize: 22 },
  input: { flex: 1, height: 36, borderRadius: 18, paddingHorizontal: 14, fontSize: 15 },
  send: { width: 36, height: 36, borderRadius: 18, alignItems: 'center', justifyContent: 'center' },
  sendText: { fontSize: 18, fontWeight: '700' },
});
```

### In production

- Persist `recent` and `tone` (AsyncStorage, MMKV) so they survive restarts; see [Recently used](../components/emoji-picker#recently-used).
- Picking an emoji adds it at the cursor and closes the sheet. For several at once, pass `closeOnSelect={false}`; the sheet then closes on a drag down or a tap on the backdrop.
- Dismiss the keyboard with `Keyboard.dismiss()` when the sheet opens, so the two don't stack.
- To show the emojis in the keyboard's place instead, render an inline `EmojiPicker` under the composer and size it to the last keyboard height (`Keyboard.addListener('keyboardDidShow', e => …)`).
- On older Android, set `maxEmojiVersion` to avoid emojis the device can't render.

---

## Country and phone number

A sign-up form where choosing a country also sets the phone number's dialing code, and the code can still be changed on its own, for someone living abroad. Both pickers are [`CountryPicker`](../components/country-picker): the second one shows a compact `🇮🇱 +972` trigger.

```tsx live
import { useState } from 'react';
import { Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
import { CountryPicker, getCountry } from '@elik56a/react-native-pickers';
import type { CountryCode } from '@elik56a/react-native-pickers';

const PREFERRED: CountryCode[] = ['US', 'GB', 'IL'];

export default function SignUp() {
  const [country, setCountry] = useState<CountryCode | null>(null);
  const [phoneCountry, setPhoneCountry] = useState<CountryCode | null>(null);
  const [phone, setPhone] = useState('');
  const prefix = phoneCountry ? getCountry(phoneCountry) : undefined;

  const chooseCountry = (code: CountryCode) => {
    setCountry(code);
    setPhoneCountry(code);
  };

  return (
    <View style={styles.form}>
      <CountryPicker label="Country" preferred={PREFERRED} value={country} onChange={chooseCountry} />
      <Text style={styles.label}>Phone</Text>
      <View style={styles.row}>
        <CountryPicker
          sheetTitle="Country code"
          preferred={PREFERRED}
          showDialCode
          value={phoneCountry}
          onChange={setPhoneCountry}
          renderTrigger={({ open }) => (
            <Pressable onPress={open} accessibilityRole="button" accessibilityLabel="Country code" style={styles.prefix}>
              <Text style={styles.text}>{prefix ? `${prefix.flag} ${prefix.dialCode}` : '+'}</Text>
            </Pressable>
          )}
        />
        <TextInput value={phone} onChangeText={setPhone} placeholder="Phone number" keyboardType="phone-pad" style={styles.input} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  form: { gap: 8 },
  label: { fontSize: 14, fontWeight: '600', marginTop: 8 },
  row: { flexDirection: 'row', gap: 8 },
  prefix: { height: 48, paddingHorizontal: 12, justifyContent: 'center', borderWidth: 1, borderColor: '#D9D4CA', borderRadius: 12 },
  text: { fontSize: 16 },
  input: { flex: 1, height: 48, paddingHorizontal: 12, borderWidth: 1, borderColor: '#D9D4CA', borderRadius: 12, fontSize: 16 },
});
```

Try searching `deutschland`, `+44`, `usa` or `日本`.

### Tips

- Send `getCountry(phoneCountry).dialCode + phone` to your server, with spaces removed: `'+1 809'` is a North American area code written as `+1 809`.
- `preferred` puts the countries most of your users pick at the top. Define it outside the component so the list is built once.
- Need your own grouping, such as by region? Build options from [`getAllCountries()`](../components/country-picker#utilities) and pass them to a [`SelectPicker`](../components/select-picker) with a `group` on each option.

---

## Duration & timer picker

A workout form with two lengths of time: the session, in 5-minute steps from 10 minutes to 3 hours, and the rest between sets, in minutes and seconds. Both are [`DurationPickerField`](../components/duration-picker#in-a-form-field)s: a bottom sheet on iOS and Android, a dropdown under the field on the web, and nothing changes until the user confirms.

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

export default function Workout() {
  const [session, setSession] = useState(45 * 60);
  const [rest, setRest] = useState(90);
  return (
    <View style={styles.form}>
      <DurationPickerField
        label="Session"
        value={session}
        onConfirm={setSession}
        min={10 * 60}
        max={3 * 3600}
        minuteInterval={5}
      />
      <DurationPickerField
        label="Rest between sets"
        title="Rest"
        value={rest}
        onConfirm={setRest}
        showHours={false}
        showSeconds
        min={15}
        max={5 * 60}
        secondInterval={15}
      />
      <Text style={styles.summary}>
        {Math.floor(session / (rest + 60))} sets of 1 min with {formatDuration(rest)} rest
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  form: { gap: 12 },
  summary: { color: '#6E685E', textAlign: 'center' },
});
```

### How it works

- **The value is seconds.** `45 * 60` goes in, and `onConfirm` hands back a number of seconds, ready to store or to start a timer with.
- **`min` and `max`** dim what's out of range, so the session can't be under 10 minutes and the rest can't be 0.
- **`showHours={false}`** leaves minutes and seconds for short times. Without hours, minutes count past 59.
- **`formatDuration`** writes seconds as the field shows them, such as `1 min 30 s`, for any text of your own.

For other units, such as feet and inches or kilograms, build the wheels with [`MultiWheelPicker`](../components/multi-wheel-picker) and a `suffix` on each column.

---

## Filters bottom sheet

A "Filters" sheet with a sort order, a status select, a date range and Reset / Apply, all applied at once. The buttons take their colours and corners from `usePickerTheme()`, so they match the pickers in light and dark mode and in each [design](../guides/designs). It uses `BottomSheet` for the layout, [`HorizontalList`](../components/horizontal-list) for the sort order, and `useDraft` so nothing changes until **Apply**.

```tsx live
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import {
  BottomSheet,
  DatePicker,
  HorizontalList,
  SelectList,
  useDraft,
  formatDate,
  usePickerTheme,
} from '@elik56a/react-native-pickers';
import type { DateRange } from '@elik56a/react-native-pickers';

type Sort = 'newest' | 'oldest' | 'priority';
type Filters = { sort: Sort; status: string[]; dates: DateRange };
const EMPTY: Filters = {
  sort: 'newest',
  status: [],
  dates: { start: null, end: null },
};
const SORTS: { label: string; value: Sort }[] = [
  { label: 'Newest', value: 'newest' },
  { label: 'Oldest', value: 'oldest' },
  { label: 'Priority', value: 'priority' },
];
const STATUSES = ['Open', 'In progress', 'Blocked', 'Done'].map((s) => ({
  label: s,
  value: s,
}));

function Button({
  title,
  onPress,
  primary,
}: {
  title: string;
  onPress: () => void;
  primary?: boolean;
}) {
  const { colors, radius } = usePickerTheme();
  return (
    <Pressable
      onPress={onPress}
      style={[
        styles.btn,
        { borderRadius: radius.md, backgroundColor: primary ? colors.primary : colors.surface },
      ]}
    >
      <Text style={[styles.btnText, { color: primary ? colors.onPrimary : colors.text }]}>
        {title}
      </Text>
    </Pressable>
  );
}

export default function FiltersExample() {
  const { colors } = usePickerTheme();
  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, { color: colors.textSecondary }]}>
        {SORTS.find((s) => s.value === filters.sort)?.label} ·{' '}
        {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, { color: colors.textSecondary }]}>Sort by</Text>
          <HorizontalList
            items={SORTS}
            value={draft.sort}
            onChange={(sort) => setDraft({ ...draft, sort })}
            accessibilityLabel="Sort by"
            style={styles.sort}
          />
          <Text style={[styles.h, { color: colors.textSecondary }]}>Status</Text>
          <SelectList
            multiple
            options={STATUSES}
            value={draft.status}
            onChange={(status) => setDraft({ ...draft, status })}
          />
          <Text style={[styles.h, { color: colors.textSecondary }]}>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',
    marginTop: 12,
    marginBottom: 4,
    marginStart: 12,
  },
  sort: { marginHorizontal: 12 },
  summary: { marginTop: 8, textAlign: 'center' },
  btn: { paddingVertical: 12, paddingHorizontal: 16, alignItems: 'center' },
  btnText: { fontWeight: '600' },
});
```

### 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`.
:::

---

## Flight search form

A booking form like the ones on airline and travel sites. The airports come from a server: the list starts empty and asks for a city, airport or code, then searches as the user types, with a loader. Trip type and cabin are segmented controls, the dates switch between one date and a range with the trip type, and **Search flights** checks everything before it goes.

**Try it:** open **From** (a dropdown on the web, a bottom sheet on the iOS and Android tabs): the list is empty and says *Type a city, airport or code*. Type `lon`: the loader shows *Finding airports…* while the fake server answers, then London's two airports appear. Type `xyz` and it says *No airport matches*.

```tsx live
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';
import {
  DatePickerField,
  HorizontalList,
  SelectPicker,
  WheelPickerField,
  formatDate,
  usePickerTheme,
} from '@elik56a/react-native-pickers';
import type { DateRange, SelectOption } from '@elik56a/react-native-pickers';

type Airport = { code: string; city: string; name: string; flag: string };

// Defined first: the option icons below use it while the module loads.
const styles = StyleSheet.create({
  form: { gap: 14 },
  flag: { fontSize: 20 },
  label: { fontSize: 13, fontWeight: '500', marginBottom: 6 },
  error: { marginTop: 4, fontSize: 12 },
  button: { paddingVertical: 14, alignItems: 'center' },
  buttonText: { fontWeight: '600', fontSize: 16 },
  summary: { textAlign: 'center' },
});

const AIRPORTS: Airport[] = [
  { code: 'TLV', city: 'Tel Aviv', name: 'Ben Gurion', flag: '🇮🇱' },
  { code: 'JFK', city: 'New York', name: 'John F. Kennedy', flag: '🇺🇸' },
  { code: 'EWR', city: 'Newark', name: 'Newark Liberty', flag: '🇺🇸' },
  { code: 'LHR', city: 'London', name: 'Heathrow', flag: '🇬🇧' },
  { code: 'LGW', city: 'London', name: 'Gatwick', flag: '🇬🇧' },
  { code: 'CDG', city: 'Paris', name: 'Charles de Gaulle', flag: '🇫🇷' },
  { code: 'AMS', city: 'Amsterdam', name: 'Schiphol', flag: '🇳🇱' },
  { code: 'FCO', city: 'Rome', name: 'Fiumicino', flag: '🇮🇹' },
  { code: 'MAD', city: 'Madrid', name: 'Barajas', flag: '🇪🇸' },
  { code: 'BER', city: 'Berlin', name: 'Brandenburg', flag: '🇩🇪' },
  { code: 'DXB', city: 'Dubai', name: 'Dubai International', flag: '🇦🇪' },
  { code: 'HND', city: 'Tokyo', name: 'Haneda', flag: '🇯🇵' },
  { code: 'SFO', city: 'San Francisco', name: 'San Francisco International', flag: '🇺🇸' },
];

const toOption = (a: Airport): SelectOption<string> => ({
  label: `${a.city} (${a.code})`,
  value: a.code,
  description: `${a.name} Airport`,
  icon: <Text style={styles.flag}>{a.flag}</Text>,
});

// Stands in for GET /airports?q=…, which matches city, code and airport name
const searchAirports = (query: string) =>
  new Promise<SelectOption<string>[]>((resolve) => {
    const q = query.trim().toLowerCase();
    const matches = AIRPORTS.filter((a) => [a.city, a.code, a.name].some((s) => s.toLowerCase().includes(q)));
    setTimeout(() => resolve(matches.map(toOption)), 900);
  });

const TRIPS = [
  { label: 'Round trip', value: 'round' },
  { label: 'One way', value: 'oneWay' },
];
const CABINS = [
  { label: 'Economy', value: 'economy' },
  { label: 'Premium', value: 'premium' },
  { label: 'Business', value: 'business' },
  { label: 'First', value: 'first' },
];
const TRAVELLERS = Array.from({ length: 9 }, (_, i) => ({
  label: `${i + 1} traveller${i ? 's' : ''}`,
  value: i + 1,
}));

const FieldError = ({ message }: { message: string | false }) => {
  const { colors } = usePickerTheme();
  return message ? <Text style={[styles.error, { color: colors.primary }]}>{message}</Text> : null;
};

export default function FlightSearch() {
  const { colors, radius } = usePickerTheme();
  const [from, setFrom] = useState<string | null>(null);
  const [to, setTo] = useState<string | null>(null);
  const [trip, setTrip] = useState('round');
  const [depart, setDepart] = useState<Date | null>(null);
  const [dates, setDates] = useState<DateRange>({ start: null, end: null });
  const [cabin, setCabin] = useState('economy');
  const [travellers, setTravellers] = useState(1);
  const [submitted, setSubmitted] = useState(false);
  const [summary, setSummary] = useState('');

  const errors = {
    from: !from && 'Where from?',
    to: !to ? 'Where to?' : to === from && 'Pick a different airport',
    dates: trip === 'round' ? (!dates.start || !dates.end) && 'Pick both dates' : !depart && 'Pick a date',
  };
  const valid = !errors.from && !errors.to && !errors.dates;

  const submit = () => {
    setSubmitted(true);
    if (!valid) return setSummary('');
    const when =
      trip === 'round' ? `${formatDate(dates.start!)} → ${formatDate(dates.end!)}` : formatDate(depart!);
    setSummary(`${from} → ${to} · ${when} · ${travellers} × ${cabin}`);
  };

  return (
    <View style={styles.form}>
      <HorizontalList items={TRIPS} value={trip} onChange={setTrip} accessibilityLabel="Trip type" />

      <View>
        <SelectPicker
          label="From"
          placeholder="City or airport"
          loadOptions={searchAirports}
          value={from}
          onChange={setFrom}
          searchPrompt="Type a city, airport or code"
          loadingText="Finding airports…"
          emptyText="No airport matches"
        />
        <FieldError message={submitted && errors.from} />
      </View>

      <View>
        <SelectPicker
          label="To"
          placeholder="City or airport"
          loadOptions={searchAirports}
          value={to}
          onChange={setTo}
          searchPrompt="Type a city, airport or code"
          loadingText="Finding airports…"
          emptyText="No airport matches"
        />
        <FieldError message={submitted && errors.to} />
      </View>

      <View>
        {trip === 'round' ? (
          <DatePickerField
            label="Dates"
            placeholder="Depart → Return"
            mode="range"
            value={dates}
            onConfirm={setDates}
            minDate={new Date()}
          />
        ) : (
          <DatePickerField label="Date" placeholder="Depart" value={depart} onConfirm={setDepart} minDate={new Date()} />
        )}
        <FieldError message={submitted && errors.dates} />
      </View>

      <WheelPickerField label="Travellers" items={TRAVELLERS} value={travellers} onConfirm={setTravellers} />

      <View>
        <Text style={[styles.label, { color: colors.textSecondary }]}>Cabin</Text>
        <HorizontalList items={CABINS} value={cabin} onChange={setCabin} accessibilityLabel="Cabin" />
      </View>

      <Pressable
        onPress={submit}
        style={[styles.button, { borderRadius: radius.md, backgroundColor: colors.primary }]}
        accessibilityRole="button"
      >
        <Text style={[styles.buttonText, { color: colors.onPrimary }]}>Search flights</Text>
      </Pressable>
      {summary ? <Text style={[styles.summary, { color: colors.text }]}>✈️ {summary}</Text> : null}
    </View>
  );
}
```

### How it's built

- **Airports from a server.** `loadOptions={searchAirports}` does the searching: it waits for a pause in typing, shows `loadingText` from the keystroke until the airports arrive, and ignores answers to older queries.
- **The right text at each step.** Before typing, the empty list shows `searchPrompt`; after a search with no results, `emptyText`. To list something before typing instead (popular or recent airports), pass them as `options`.
- **Search by anything.** The server matches city, code and airport name, so `tlv`, `heathrow` and `new york` all work. The list shows what it returns without filtering again.
- **The picked airport keeps its label** after a later search no longer returns it.
- **Trip type** is a segmented [`HorizontalList`](../components/horizontal-list); it swaps the dates field between a range and a single date. **Cabin** is another, with four options that scroll if the screen is narrow.
- **Theme colours.** The labels, errors and **Search flights** read `usePickerTheme()`, so the form matches the pickers in dark mode and in each [design](../guides/designs); Material's fields float their labels, the others show them above.
- **Validation** runs on submit and shows a message under each field, including **From** and **To** being the same airport.

### With your API

Replace the stand-in with a real request. `loadOptions` takes any function that returns a promise of options:

```tsx
const searchAirports = async (query: string) => {
  const res = await fetch(`https://api.example.com/airports?q=${encodeURIComponent(query)}`);
  if (!res.ok) throw new Error(`Airport search failed: ${res.status}`);
  const airports: Airport[] = await res.json();
  return airports.map(toOption);
};
```

A rejected promise shows `emptyText`. Set `searchDebounce` (300 ms by default) higher for a slow or rate-limited API.

In a form library, wire the fields the same way as in the [forms guide](../guides/forms): `value={field.value}` and `onChange={field.onChange}` on the `SelectPicker`, `onConfirm={field.onChange}` on the fields.

---

## Search a server

Options that come from an API. `loadOptions` covers most cases in one line; `onSearchChange` is there when you need pagination or your own cache.

### With `loadOptions`

Give it a function from the query to the options. The picker waits for a pause in typing, shows the loader from the keystroke until the results arrive, and ignores answers to older queries. It starts empty with `searchPrompt`, since `options` (shown before the user types) isn't passed, and says `emptyText` when a search finds nobody.

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

const NAMES = ['Ada Lovelace', 'Alan Turing', 'Barbara Liskov', 'Dennis Ritchie', 'Donald Knuth', 'Edsger Dijkstra', 'Frances Allen', 'Grace Hopper', 'Guido van Rossum', 'Hedy Lamarr', 'Ken Thompson', 'Linus Torvalds', 'Margaret Hamilton', 'Radia Perlman', 'Tim Berners-Lee'];

// Stands in for GET /users?q=…
const searchUsers = (query: string) =>
  new Promise<{ label: string; value: string; description: string }[]>((resolve) =>
    setTimeout(
      () =>
        resolve(
          NAMES.filter((n) => n.toLowerCase().includes(query.toLowerCase())).map((name) => ({
            label: name,
            value: name,
            description: `@${name.split(' ')[0].toLowerCase()}`,
          }))
        ),
      600
    )
  );

export default function Example() {
  const [user, setUser] = useState<string | null>(null);
  return (
    <SelectPicker
      label="Assignee"
      placeholder="Search people"
      value={user}
      onChange={setUser}
      loadOptions={searchUsers}
      searchPrompt="Type a name"
      loadingText="Searching people…"
      emptyText="Nobody by that name"
      clearable
      onClear={() => setUser(null)}
    />
  );
}
```

`searchDebounce` sets the wait after the last keystroke (300 ms by default; `0` searches on every keystroke). A rejected promise shows `emptyText`. For several fields like this in one form, see the [flight search form](./flight-search-form).

### With `onSearchChange`, and pages

When the server pages its results, keep the options yourself: `onSearchChange` gives you the query once typing pauses, `loading` shows the loader (under the options once some are showing), and `onEndReached` asks for the next page.

```tsx live
import { useEffect, useRef, useState } from 'react';
import { SelectPicker } from '@elik56a/react-native-pickers';
import type { SelectOption } from '@elik56a/react-native-pickers';

const NAMES = Array.from({ length: 40 }, (_, i) => `Customer ${i + 1}`);
const PAGE = 10;

// Stands in for GET /customers?q=…&offset=…
const fetchCustomers = (query: string, offset: number) =>
  new Promise<{ names: string[]; hasMore: boolean }>((resolve) => {
    const matches = NAMES.filter((n) => n.toLowerCase().includes(query.toLowerCase()));
    setTimeout(() => resolve({ names: matches.slice(offset, offset + PAGE), hasMore: offset + PAGE < matches.length }), 600);
  });

export default function Example() {
  const [customer, setCustomer] = useState<string | null>(null);
  const [query, setQuery] = useState('');
  const [options, setOptions] = useState<SelectOption<string>[]>([]);
  const [loading, setLoading] = useState(false);
  const [hasMore, setHasMore] = useState(false);
  const latest = useRef('');

  const load = (q: string, offset: number) => {
    latest.current = q;
    setLoading(true);
    fetchCustomers(q, offset).then(({ names, hasMore: more }) => {
      if (latest.current !== q) return; // an older query answered late
      const page = names.map((name) => ({ label: name, value: name }));
      setOptions((current) => (offset ? [...current, ...page] : page));
      setHasMore(more);
      setLoading(false);
    });
  };

  useEffect(() => load(query, 0), [query]);

  return (
    <SelectPicker
      label="Customer"
      options={options}
      value={customer}
      onChange={setCustomer}
      onSearchChange={setQuery}
      loading={loading}
      onEndReached={() => {
        if (hasMore && !loading) load(query, options.length);
      }}
      listHeight={280}
    />
  );
}
```

Closing the picker calls `onSearchChange('')`, so the next open starts from the first page of everything.

### A custom loader

`renderLoading` replaces the spinner and text. Here, skeleton rows shaped like the options:

```tsx live
import { StyleSheet, View } from 'react-native';
import { SelectList } from '@elik56a/react-native-pickers';
import type { PickerTheme } from '@elik56a/react-native-pickers';

const Skeleton = ({ theme }: { theme: PickerTheme }) => (
  <View style={styles.skeleton}>
    {[0.7, 0.5, 0.6].map((width) => (
      <View key={width} style={styles.row}>
        <View style={[styles.avatar, { backgroundColor: theme.colors.surface }]} />
        <View style={[styles.line, { width: `${width * 100}%`, backgroundColor: theme.colors.surface }]} />
      </View>
    ))}
  </View>
);

export default function Example() {
  return <SelectList options={[]} loading renderLoading={(theme) => <Skeleton theme={theme} />} />;
}

const styles = StyleSheet.create({
  skeleton: { flex: 1, gap: 14 },
  row: { flexDirection: 'row', alignItems: 'center', gap: 12 },
  avatar: { width: 32, height: 32, borderRadius: 16 },
  line: { height: 12, borderRadius: 6 },
});
```

---

## 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 { StyleSheet, Text, View } from 'react-native';
import { SelectPicker, usePickerTheme } 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 { colors } = usePickerTheme();
  const [tags, setTags] = useState<string[]>(['climbing', 'ai']);
  return (
    <View style={styles.root}>
      <SelectPicker
        multiple
        label="Interests"
        placeholder="Add interests"
        sheetTitle={`Pick up to ${MAX}`}
        options={options}
        value={tags}
        onChange={setTags}
        maxSelected={MAX}
        clearable
      />
      <Text style={[styles.hint, { color: colors.textSecondary }]}>
        {tags.length}/{MAX} selected · tap a chip to remove it
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 6 },
  hint: { fontSize: 12 },
});
```

### 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 package with zero native code 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 + time in one picker | ✅ | ⚠️ iOS only | ❌ | ❌ |
| Date **range** selection | ✅ built in | ❌ | ⚠️ via manual marking | ❌ |
| Multiple dates | ✅ | ❌ | ⚠️ manual | ❌ |
| Searchable select / multi-select | ✅ | ❌ | ❌ | ⚠️ varies |
| Server search (async options) | ✅ `loadOptions` | ❌ | ❌ | ❌ |
| Segmented control / chips | ✅ `HorizontalList` | ⚠️ separate native package | ❌ | ❌ |
| Emoji picker | ✅ | ❌ | ❌ | ❌ |
| Bottom sheets | ✅ built in | ❌ | ❌ | ❌ |
| Keyboard navigation on the web | ✅ arrows, Home/End, Esc | — | ⚠️ varies | ⚠️ varies |
| Native look per platform (iOS, Material, web) | ✅ | ✅ | ❌ | ⚠️ iOS / Android only |
| One look on every platform, if you want it | ✅ `design="ios"` | ❌ | ✅ | ❌ |
| 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 pickers that **look native on iOS, Android and the web** and still match your brand, or one design on every platform
- 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's own control**, for example to get every system accessibility feature or follow each OS update automatically. Our designs follow iOS and Material, but they're drawn in JavaScript. 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/index.mdx) for prop-by-prop guides 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/`.

The component pages and their prop playgrounds are listed once, in `website/src/catalog/` (`catalog.constants.ts` and `playgrounds.tsx`): the docs sidebar, each page's playground and the example app's drawer all read it, and the example app shows the docs' showcase screens. A new component or prop control goes there.

### 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 look native on iOS and Android?

Yes. By default each platform gets its own design: the iOS design on iOS, Material Design on Android (outlined fields, radios, a clock dial, **OK** under the content) and a web design in the browser. See [Designs](../guides/designs).

### Can I use the iOS look on Android too, or one look everywhere?

Yes. `<PickersProvider design="ios">` uses the iOS design on every platform; `"material"` and `"web"` work the same way. A component's own `design` prop wins over the provider's.

### How much can I customize?

Everything. Colors, radius, spacing and fonts are theme tokens (light and dark), every visual part takes a style through `styles`, and render props replace rows, days, triggers and chevrons. Your settings always win over the design. See [Theming](../guides/theming) and [Styling with slots](../guides/styling).

### 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?

Yes, with [`DateTimePicker`](../components/date-time-picker): one row of wheels on iOS, a calendar with the time under it in Material, or beside it on the web. In a form, use `DateTimePickerField`.

```tsx
<DateTimePicker value={when} onChange={setWhen} minuteInterval={5} />
```

### 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 load options from an API?

Pass `loadOptions={(query) => api.search(query)}` to `SelectPicker` or `SelectList`. The list waits for a pause in typing, shows a loader until the results arrive, and ignores answers to older queries. For pagination or your own caching, use `onSearchChange` with `loading` and `onEndReached` instead. See [Search a server](../recipes/server-search).

### Does it work with React Native Web?

Yes, with the same components and props. On the web, fields and `SelectPicker` open a dropdown under the field, sheets open as a centered modal on wide windows, and pickers use the web design. See [Platforms](../guides/platforms).

### 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 from react-native-country-picker-modal

## Migrate from `react-native-country-picker-modal`

`CountryPicker` is a form field like the others: it shows the chosen country and opens a searchable list, a bottom sheet on phones and a dropdown on the web. Flags are emoji, so nothing is downloaded, and names follow the device language through `Intl`. The value is the ISO code; [`getCountry`](../../components/country-picker#utilities) gives the name, flag and dialing code.

```diff
- import CountryPicker from 'react-native-country-picker-modal';
+ import { CountryPicker } from '@elik56a/react-native-pickers';

- <CountryPicker
-   countryCode={code}
-   withFilter
-   withCallingCode
-   onSelect={(country) => setCode(country.cca2)}
- />
+ <CountryPicker label="Country" showDialCode value={code} onChange={setCode} />
```

| react-native-country-picker-modal | React Native Pickers |
| --- | --- |
| `countryCode` | `value` |
| `onSelect(country)` | `onChange(code, option)`; `getCountry(code)` for the details |
| `countryCodes` | `countries` |
| `excludeCountries` | `exclude` |
| `preferredCountries` | `preferred` (kept on top under their own header, with search too) |
| `region` / `subregion` | `countries` with that region's codes |
| `withFilter` | search is built in |
| `withCallingCode` | `showDialCode` |
| `withFlag` / `withEmoji` | always on: emoji flags, nothing to download |
| `translation` | `locale`, any language `Intl` knows |
| `withAlphaFilter` | search instead; it also matches native names, ISO codes and `+44` |
| `placeholder` | `placeholder` |
| `visible` / `onOpen` / `onClose` | `onOpen` / `onClose`; `renderTrigger` for your own button |
| `withCallingCodeButton` for a phone input | [`PhoneField`](../../components/phone-field) |
| `withCurrency` / `withCurrencyButton` | no equivalent |
| — | `multiple`, `clearable`, iOS, Material and web designs |

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from @react-native-community/datetimepicker

## Migrate from `@react-native-community/datetimepicker`

```diff
- import DateTimePicker from '@react-native-community/datetimepicker';
+ import { DatePicker, DateTimePicker, 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 mode="datetime" value={when} onChange={(e, d) => d && setWhen(d)} />
+ <DateTimePicker value={when} onChange={setWhen} />
```

| datetimepicker | React Native Pickers |
| --- | --- |
| `mode="date"` | `DatePicker` (calendar) or `DatePicker display="wheel"` |
| `mode="time"` | `TimePicker` |
| `mode="datetime"` | [`DateTimePicker`](../../components/date-time-picker) |
| `display="spinner"` | `DatePicker display="wheel"`, `TimePicker display="wheel"` |
| `display="clock"` (Android) | `TimePicker display="dial"` (the default in the Material design) |
| `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)) |

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-dropdown-picker

## Migrate from `react-native-dropdown-picker`

`SelectPicker` keeps its own open state, so `open`, `setOpen` and `setItems` go away, and `onChange` gets the new value rather than an updater. It opens as a dropdown on the web and a bottom sheet on phones, where a dropdown is cramped; set `presentation="dropdown"` to keep the dropdown everywhere.

```diff
- import DropDownPicker from 'react-native-dropdown-picker';
+ import { SelectPicker } from '@elik56a/react-native-pickers';

- const [open, setOpen] = useState(false);
  const [value, setValue] = useState(null);
- const [items, setItems] = useState([
-   { label: 'Apple', value: 'apple' },
-   { label: 'Banana', value: 'banana' },
- ]);
-
- <DropDownPicker open={open} value={value} items={items} setOpen={setOpen} setValue={setValue} setItems={setItems} />
+ <SelectPicker
+   options={[{ label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }]}
+   value={value}
+   onChange={setValue}
+ />
```

| react-native-dropdown-picker | React Native Pickers |
| --- | --- |
| `items` + `setItems` | `options` (adds `description`, `icon`, `group`, `keywords`) |
| `value` + `setValue` | `value` + `onChange(value, option)` |
| `open` + `setOpen` | not needed; `onOpen` / `onClose` if you want to know |
| `onChangeValue` | `onChange` |
| `multiple` | `multiple` (selected items show as removable chips) |
| `min` / `max` | `maxSelected`; check a minimum in your form |
| `searchable` | `searchable` (on by default past 8 options) |
| `searchPlaceholder` | `searchPlaceholder` |
| `onChangeSearchText` + `disableLocalSearch` + `loading` | `onSearchChange` + `loading`, or `loadOptions(query)` that returns a promise |
| `placeholder` | `placeholder` |
| `disabled` | `disabled` |
| `listMode="MODAL"` | `presentation="modal"` |
| `listMode="FLATLIST"` / `"SCROLLVIEW"` | `presentation="dropdown"` |
| `renderListItem` | `renderOption({ option, selected, disabled, theme })` |
| `addCustomItem` | no equivalent; add the typed text to `options` yourself |

See [SelectPicker](../../components/select-picker) for groups, icons and render props, and [server search](../../recipes/server-search).

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-element-dropdown

## Migrate from `react-native-element-dropdown`

`Dropdown` and `MultiSelect` are one component, `SelectPicker`, with `multiple` for the second. Options always have `label` and `value`, so `labelField` and `valueField` go away, and `onChange` gets the value with the option next to it.

```diff
- import { Dropdown } from 'react-native-element-dropdown';
+ import { SelectPicker } from '@elik56a/react-native-pickers';

- <Dropdown
-   data={fruits}
-   labelField="label"
-   valueField="value"
-   placeholder="Select a fruit"
-   search
-   searchPlaceholder="Search..."
-   value={value}
-   onChange={(item) => setValue(item.value)}
- />
+ <SelectPicker
+   options={fruits}
+   placeholder="Select a fruit"
+   searchable
+   searchPlaceholder="Search..."
+   value={value}
+   onChange={setValue}
+ />
```

| react-native-element-dropdown | React Native Pickers |
| --- | --- |
| `Dropdown` / `MultiSelect` | `SelectPicker` / `SelectPicker multiple` |
| `data` + `labelField` + `valueField` | `options`, mapped to `{ label, value }` once: `data.map((d) => ({ label: d.name, value: d.id }))` |
| `value` | `value` (an array with `multiple`) |
| `onChange(item)` | `onChange(value, option)` |
| `placeholder` | `placeholder` |
| `search` | `searchable` (on by default past 8 options) |
| `searchPlaceholder` | `searchPlaceholder` |
| `searchQuery` | `filterOption(option, query)`; `keywords` on an option are searched too |
| `maxSelect` | `maxSelected` |
| `disable` | `disabled` |
| `mode="modal"` | `presentation="modal"` |
| `renderItem(item, selected)` | `renderOption({ option, selected, disabled, theme })` |
| `renderLeftIcon` | `icon` on each option, shown in the field for the selected one |
| `renderSelectedItem` | chips by default; `renderTrigger` for your own field |
| `maxHeight` | `listHeight` |

See [SelectPicker](../../components/select-picker) for groups, icons and server search.

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from rn-emoji-keyboard

## Migrate from `rn-emoji-keyboard`

`EmojiPickerSheet` takes `visible` and `onClose` like the other sheets, and `onSelect` gets the emoji string first. Search and recently used are on by default. Skin tones are built in, and the category bar sits where the platform's own emoji keyboard has it. For a picker inside your own layout, use [`EmojiPicker`](../../components/emoji-picker).

```diff
- import EmojiPicker from 'rn-emoji-keyboard';
+ import { EmojiPickerSheet } from '@elik56a/react-native-pickers';

- <EmojiPicker open={open} onClose={() => setOpen(false)} onEmojiSelected={(e) => setEmoji(e.emoji)} />
+ <EmojiPickerSheet visible={open} onClose={() => setOpen(false)} onSelect={setEmoji} />
```

| rn-emoji-keyboard | React Native Pickers |
| --- | --- |
| `open` | `visible` |
| `onClose` / `onRequestClose` | `onClose` |
| `onEmojiSelected({ emoji, name, … })` | `onSelect(emoji, data)`; `data` has `name`, `keywords`, `category`, `version`, `skins` |
| `allowMultipleSelections` | `closeOnSelect={false}` |
| `enableSearchBar` | `searchable` (on by default) |
| `enableRecentlyUsed` | `showRecent` (on by default); `recent` / `onRecentChange` to keep them |
| `categoryPosition="top" \| "bottom"` | `categoryBarPosition="top" \| "bottom"` |
| `disabledCategories` | `categories` lists the ones to show |
| `categoryOrder` | the order of `categories` |
| `emojiSize` | `emojiSize` |
| `defaultHeight` | `sheetProps={{ height }}` |
| `translation` | `categoryLabels`, `searchPlaceholder`, `emptyText` |
| `theme` / `styles` | `theme` tokens and `styles` slots |
| `selectedEmojis` | no equivalent |
| — | `maxEmojiVersion` to hide emoji older phones can't draw, `exclude` |

See [EmojiPicker](../../components/emoji-picker) for skin tones, recents and the field.

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate to React Native Pickers

## Migration

Prop-by-prop guides from popular packages. Most migrations are a rename plus switching callbacks to `(value) => …`.

Compared with native pickers, your users keep a native look: the iOS design on iOS and Material Design on Android, by default. Set `design="ios"` on `PickersProvider` if you'd rather show the same look everywhere. See [Designs](../../guides/designs.mdx).

| Coming from | Use |
| --- | --- |
| [`@react-native-community/datetimepicker`](./datetimepicker.mdx) | `DatePicker`, `TimePicker`, `DateTimePicker` |
| [`react-native-date-picker`](./react-native-date-picker.mdx) | `DateWheelPicker`, `TimePicker`, `DatePickerSheet` |
| [`react-native-modal-datetime-picker`](./modal-datetime-picker.mdx) | `DatePickerSheet`, `TimePickerSheet`, `DateTimePickerSheet` |
| [`react-native-calendars`](./react-native-calendars.mdx) | `DatePicker` |
| [`react-native-picker-select`](./picker-select.mdx) | `SelectPicker` |
| [`react-native-dropdown-picker`](./dropdown-picker.mdx) | `SelectPicker` |
| [`react-native-element-dropdown`](./element-dropdown.mdx) | `SelectPicker` |
| [`@react-native-picker/picker`](./picker.mdx) | `WheelPicker` or `SelectPicker` |
| [`@react-native-segmented-control/segmented-control`](./segmented-control.mdx) | `HorizontalList` |
| [`react-native-country-picker-modal`](./country-picker-modal.mdx) | `CountryPicker` |
| [`react-native-phone-number-input`](./phone-number-input.mdx) | `PhoneField` |
| [`rn-emoji-keyboard`](./emoji-keyboard.mdx) | `EmojiPickerSheet` |

Not sure it's the right fit? [Comparison](../comparison.mdx) shows when another library is the better choice.

---

## Migrate from react-native-modal-datetime-picker

## Migrate 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" \| "datetime"` | `DatePickerSheet` · `TimePickerSheet` · `DateTimePickerSheet` |
| `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`.

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-phone-number-input

## Migrate from `react-native-phone-number-input`

`PhoneField` gives you the E.164 number in `onChange`, with the country and a length check next to it, so there's no ref to call. It formats the number as it's typed for about 50 countries and picks the country from a pasted `+44…` number. It doesn't bundle libphonenumber, so `valid` checks the length only; verify the number on your server, as with an SMS code.

```diff
- import PhoneInput from 'react-native-phone-number-input';
+ import { PhoneField } from '@elik56a/react-native-pickers';

- const phoneInput = useRef<PhoneInput>(null);
- <PhoneInput
-   ref={phoneInput}
-   defaultCode="US"
-   defaultValue={value}
-   onChangeFormattedText={setPhone}
- />
- const valid = phoneInput.current?.isValidNumber(value);
+ <PhoneField
+   defaultCountry="US"
+   value={phone}
+   onChange={(value, { valid }) => {
+     setPhone(value);
+     setValid(valid);
+   }}
+ />
```

| react-native-phone-number-input | React Native Pickers |
| --- | --- |
| `defaultCode` | `defaultCountry`, or `country` + `onCountryChange` |
| `defaultValue` / `value` | `defaultValue` / `value`, both E.164 |
| `onChangeFormattedText` | `onChange(value)`: `'+12015550123'` |
| `onChangeText` | `onChange`'s `details.nationalNumber` |
| `onChangeCountry(country)` | `onCountryChange(code)`; `getCountry(code)` for the details |
| `ref.isValidNumber(number)` | `onChange`'s `details.valid`, or `isValidPhone(digits, country)` |
| `ref.getCallingCode()` | `getCountry(code).dialCode` |
| `ref.getNumberAfterPossiblyEliminatingZero()` | done for you: a leading trunk 0 is dropped |
| `placeholder` | `placeholder` (default: an example in the country's format) |
| `disabled` | `disabled` |
| `withDarkTheme` | `<PickersProvider colorScheme="dark">`, or `'auto'` |
| `containerStyle` / `textInputStyle` / `codeTextStyle` / `flagButtonStyle` | `styles={{ field, input, dialCode, countryButton }}` |
| `countryPickerProps` | `preferred`, `countries`, `exclude`, `locale`, `presentation`, `sheet` |
| `layout="first" \| "second"` | one layout: the flag and code, then the number |

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-picker-select

## Migrate 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).

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from @react-native-picker/picker

## Migrate 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).

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-calendars

## Migrate 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`) |

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from react-native-date-picker

## Migrate from `react-native-date-picker`

`react-native-date-picker` draws native wheels, so it needs a development build and has no web support. React Native Pickers draws the same wheels in JavaScript: it runs in Expo Go, ships in OTA updates and works on the web. Each platform gets its own design by default (wheels on iOS, a calendar and clock dial in Material); add `display="wheel"` to keep wheels everywhere.

```diff
- import DatePicker from 'react-native-date-picker';
+ import { DatePickerSheet, DateWheelPicker, TimePicker } from '@elik56a/react-native-pickers';

- <DatePicker mode="date" date={date} onDateChange={setDate} />
+ <DateWheelPicker value={date} onChange={setDate} />

- <DatePicker mode="time" date={time} onDateChange={setTime} minuteInterval={5} />
+ <TimePicker display="wheel" value={time} onChange={setTime} minuteInterval={5} />

- <DatePicker
-   modal
-   open={open}
-   date={date}
-   onConfirm={(d) => {
-     setOpen(false);
-     setDate(d);
-   }}
-   onCancel={() => setOpen(false)}
- />
+ <DatePickerSheet display="wheel" visible={open} value={date} onConfirm={setDate} onClose={() => setOpen(false)} />
```

| react-native-date-picker | React Native Pickers |
| --- | --- |
| `mode="date"` | [`DateWheelPicker`](../../components/date-wheel-picker), or [`DatePicker`](../../components/date-picker) for a calendar |
| `mode="time"` | [`TimePicker`](../../components/time-picker) with `display="wheel"` |
| `mode="datetime"` | [`DateTimePicker`](../../components/date-time-picker) with `display="wheel"` |
| `modal` + `open` | `DatePickerSheet` / `TimePickerSheet` / `DateTimePickerSheet` with `visible` |
| `date` | `value` |
| `onDateChange` | `onChange` |
| `onConfirm(date)` | `onConfirm(date)`; `onClose` is called right after, so you don't close it yourself |
| `onCancel` | `onClose` |
| `title` | `title` |
| `confirmText` / `cancelText` | `confirmLabel` / `cancelLabel` |
| `minimumDate` / `maximumDate` | `minDate` / `maxDate` |
| `minuteInterval` | `minuteInterval` |
| `locale` | `locale` (names and order from `Intl`) |
| `is24hourSource` | `format="12h"` or `"24h"` (default `'auto'`, from the locale) |
| `theme="light" \| "dark" \| "auto"` | `<PickersProvider colorScheme="light" \| "dark" \| "auto">` |
| `dividerColor` / `buttonColor` | `theme={{ colors: { indicator, primary } }}` |
| A button that opens the modal | [`DatePickerField`](../../components/picker-fields) / `TimePickerField` / `DateTimePickerField`, which hold the open state and show the value |

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Migrate from @react-native-segmented-control/segmented-control

## Migrate from `@react-native-segmented-control/segmented-control`

```diff
- import SegmentedControl from '@react-native-segmented-control/segmented-control';
+ import { HorizontalList } from '@elik56a/react-native-pickers';

- <SegmentedControl
-   values={['Day', 'Week', 'Month']}
-   selectedIndex={index}
-   onChange={(e) => setIndex(e.nativeEvent.selectedSegmentIndex)}
- />
+ <HorizontalList
+   items={[{ label: 'Day', value: 'day' }, { label: 'Week', value: 'week' }, { label: 'Month', value: 'month' }]}
+   value={view}
+   onChange={setView}
+ />
```

| segmented-control | React Native Pickers |
| --- | --- |
| `values` (strings) | `items` (`{ label, value, disabled?, icon? }`) |
| `selectedIndex` | `value` (the item's value, not its index) |
| `onChange(event)` / `onValueChange(label)` | `onChange(value, item)` |
| `enabled={false}` | `disabled: true` on each item |
| `tintColor` / `backgroundColor` | `theme={{ colors: { primary, surface } }}` or `styles={{ thumb, container }}` |
| — | scrolls sideways when the items don't fit, `variant="chips"`, `renderItem`, works on the web |

[`HorizontalList`](../../components/horizontal-list) has no native code, so it runs in Expo Go and on the web.

See [all migration guides](./index.mdx) for other libraries, and [Comparison](../comparison.mdx) for when another library is the better choice.

---

## Troubleshooting

#### After upgrading, Android or the web no longer look like iOS

Since 0.11 each platform gets its own [design](../guides/designs): Material on Android, a web design in the browser. To keep the iOS look everywhere, set `<PickersProvider design="ios">`.

#### 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.