# Timezone Select

> React time zone picker on Base UI Combobox: search by city, UTC offset or abbreviation, live local times, region groups and the user's zone pinned on top.

- Kind: Component (Forms)
- Docs: https://ui.minidev.pro/docs/timezone-select
- Source (registry JSON with the full file): https://ui.minidev.pro/r/timezone-select.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it in scheduling, settings and onboarding forms. Search by city ("new york"), zone id ("america/"), offset ("+5:30", "-8") or abbreviation ("PST"). The user's own zone is pinned at the top as Detected and is the default value. All data comes from the browser's `Intl` API, so there is no time zone file to ship or update. Built on Base UI Combobox; for any other searchable list use Combobox, and for languages use LanguagePicker.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/timezone-select
```

Writes `components/ui/timezone-select.tsx` and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/timezone-select.json`.

### npm package

```bash
npm i minidev-ui-kit @base-ui/react lucide-react
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { TimezoneSelect } from "@/components/ui/timezone-select"
```

From the npm package:

```tsx
import { TimezoneSelect } from "minidev-ui-kit/ui/timezone-select"
```

## Usage

```tsx
import { TimezoneSelect } from "@/components/ui/timezone-select"

export function Example() {
  return (
    <TimezoneSelect />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | - | no | Controlled IANA zone id, e.g. "America/New_York". |
| `defaultValue` | `string` | - | no | Starting zone when uncontrolled. Defaults to the browser's zone (`Intl.DateTimeFormat().resolvedOptions().timeZone`). |
| `onValueChange` | `(timeZone: string) => void` | - | no | Fires with the picked IANA zone id. |
| `zones` | `string[]` | - | no | Zone ids to offer. Defaults to every zone the browser knows (`Intl.supportedValuesOf("timeZone")`). |
| `showCurrentTime` | `boolean` | `true` | no | Show each zone's current local time in the list. |
| `groupByRegion` | `boolean` | `true` | no | Group zones under their region (America, Europe...). When false, one list sorted by offset. |
| `placeholder` | `string` | `"Select a time zone"` | no | Trigger text while nothing is selected. |
| `disabled` | `boolean` | - | no | Disables the trigger. |
| `id` | `string` | - | no | Id for the trigger, so a `<label htmlFor>` or FormField can name it. |
| `name` | `string` | - | no | Submits the selected zone id under this name inside a `<form>`. |
| `required` | `boolean` | - | no | Requires a selection before the form submits. |
| `aria-label` | `string` | - | no | Accessible name when there is no visible label. Defaults to "Time zone" when no `id` is passed. |
| `className` | `string` | - | no | Classes for the trigger button (width defaults to w-72). |

## Examples

### Controlled field

Pair it with FormField through the same id. The value is an IANA id you can pass straight to Intl or your date library.

```tsx
function ReminderSettings() {
  const [tz, setTz] = React.useState("America/New_York")
  return (
    <FormField id="reminder-tz" label="Send reminders in" description="Overdue reminders go out at 9:00 local time.">
      <TimezoneSelect id="reminder-tz" value={tz} onValueChange={setTz} />
    </FormField>
  )
}
```

### Your own short list

Pass zones to offer only the ones that matter. Without groups the list is sorted by offset, Detected stays on top.

```tsx
<TimezoneSelect
  aria-label="Office"
  defaultValue="Europe/London"
  zones={["America/Los_Angeles", "America/New_York", "Europe/London", "Europe/Berlin", "Asia/Kolkata", "Asia/Tokyo"]}
  groupByRegion={false}
/>
```

### Plain form submit

With name, the zone id is posted like any input. Uncontrolled, it starts on the browser's own zone.

```tsx
<form onSubmit={(e) => { e.preventDefault(); save(new FormData(e.currentTarget).get("timezone")) }}>
  <FormField id="member-tz" label="Working hours time zone">
    <TimezoneSelect id="member-tz" name="timezone" required />
  </FormField>
  <Button type="submit" size="sm">Save</Button>
</form>
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `Enter` or `Space` or `ArrowDown` | On the trigger, opens the list with the search field focused. |
| `ArrowDown` or `ArrowUp` | Moves the highlight through the matching zones, across region groups. |
| `Enter` | Selects the highlighted zone and closes the list. |
| `Escape` | Closes the list and returns focus to the trigger. |

## Accessibility

- Each region is a Base UI group with `role="group"`, labelled by its heading (Detected, America, Europe...). Zones are `role="option"` with `aria-selected`; the check icon is `aria-hidden`.
- Without `aria-label` or `id`, the trigger is named "Time zone". With an `id`, it is named by your `<label htmlFor>` or [`FormField`](https://ui.minidev.pro/docs/form-field) instead. The search field is labelled "Search time zones".

## FAQ

### Where does the time zone list come from?

From the browser: `Intl.supportedValuesOf("timeZone")`, plus `UTC` when it is missing. Offsets come from `Intl.DateTimeFormat` with `timeZoneName: "longOffset"` for today's date, so daylight saving time is right and there is no data file to update. Pass `zones` to offer your own list; an id the browser does not know stays selectable and shows UTC+00:00.

### How do I get the detected zone before the user picks one?

`onValueChange` only fires on a pick. Uncontrolled, the field shows the browser's zone ("UTC" during server rendering and hydration), and with `name` it submits that zone with the form. To save it without a form, read `Intl.DateTimeFormat().resolvedOptions().timeZone` in an effect.

### What can users type to find a zone?

A city ("new york"), part of the id ("america/argentina"), an offset (`+5:30`, `+05:30`, `+0530`, `utc-8`) or an abbreviation ("PST"). A whole-hour offset like `+5` matches +05:00, +05:30 and +05:45, not +10:00. Abbreviations are Intl's short names in `en-US` and the user's locale, so "IST" only matches where that locale uses it.

### Do the local times keep ticking?

No. Offsets and times are computed when the list opens and stay fixed while it is open. Reopening refreshes them. Set `showCurrentTime={false}` to drop the time column.

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `@base-ui/react`, `lucide-react`

## Related

- [Combobox](https://ui.minidev.pro/docs/combobox/md): Shadcn style combobox: a popover select with a filter input, check mark on the chosen item and an empty message. Built on Base UI popover for React.
- [Language Picker](https://ui.minidev.pro/docs/language-picker/md): A grid of language options exposed as an accessible listbox, with the selected language outlined in the accent color. Plug it into locale or profile settings.
- [Autocomplete](https://ui.minidev.pro/docs/autocomplete/md): Text input that filters string options as you type, using ARIA combobox and listbox roles. Works controlled or uncontrolled and lists up to eight matches.
- [Calendar Month](https://ui.minidev.pro/docs/calendar-month/md): Month calendar grid with weekday headers and clickable day cells that highlight the selected date. A simple Tailwind base for date views and schedulers.
- [Character Count](https://ui.minidev.pro/docs/character-count/md): Live React character counter that shows the current count against a limit and turns red when it goes over. Announces changes politely to screen readers.
- [Checkbox Group](https://ui.minidev.pro/docs/checkbox-group/md): Vertical wrapper that groups related checkboxes under role group with even spacing. Use it with Checkbox and labels for multi select settings.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
