# React Native Time Zone Picker

> React Native time zone picker: every IANA zone with its GMT offset and name, sorted by offset, search by city, offset or IANA name, the device's zone on top. Works on Hermes; pure JS, works in Expo Go.

# 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 [`Select`](./select) 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 'patine-ui';
```

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

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

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

## Example: plan a call across time zones

A meeting scheduler: the call is at 16:00 in your zone, and picking where your guest is shows their local time and whether it falls in their working day.

```tsx live
import { useState } from 'react';
import { Box, Text, TimeZonePicker, VStack } from 'patine-ui';

const MEETING = new Date(Date.UTC(2026, 10, 24, 15, 0));
const local = (zone: string) => new Intl.DateTimeFormat('en-GB', { timeZone: zone, weekday: 'short', hour: '2-digit', minute: '2-digit' }).format(MEETING);
const hourIn = (zone: string) => Number(new Intl.DateTimeFormat('en-GB', { timeZone: zone, hour: 'numeric', hourCycle: 'h23' }).format(MEETING));

export default function Example() {
  const [zone, setZone] = useState<string | null>('America/New_York');
  const hour = zone ? hourIn(zone) : 12;
  const ok = hour >= 9 && hour < 18;
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 420 }}>
      <VStack gap="xs">
        <Text weight="semibold">Contract review with Jordan</Text>
        <Text color="textSecondary">Tue, Nov 24 · 16:00 in Amsterdam</Text>
      </VStack>
      <TimeZonePicker label="Jordan is in" preferred={['America/New_York', 'America/Los_Angeles', 'Asia/Tokyo']} value={zone} onValueChange={setZone} date={MEETING} />
      {zone ? (
        <Text color={ok ? 'success' : 'warning'}>
          {local(zone)} for Jordan · {ok ? 'within working hours' : hour < 9 ? 'before their day starts' : 'after their day ends'}
        </Text>
      ) : null}
    </Box>
  );
}
```

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

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} onValueChange={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 'patine-ui';

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} onValueChange={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'`, or `null` where the engine can't tell |
| `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 [`Select` prop](./select#api) 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 when zones are pinned. |
| `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` | `Partial<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. |

## Related

- [Select](./select): the field it's built on, with every prop
- [DateTimePicker](./date-time-picker): the date and time to pair with the zone
- [CountryPicker](./country-picker): the same field with countries
