Skip to content

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.

src/registry/ui/timezone-select.tsx/r/timezone-select.json

Installation

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

MiniDev UI is in the shadcn registry directory, so the short form works with no setup. Older CLI versions can use the full URL: npx shadcn@latest add https://ui.minidev.pro/r/timezone-select.json

Usage

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

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

API reference

TimezoneSelect props
PropTypeDefault
valueControlled IANA zone id, e.g. "America/New_York".string-
defaultValueStarting zone when uncontrolled. Defaults to the browser's zone (`Intl.DateTimeFormat().resolvedOptions().timeZone`).string-
onValueChangeFires with the picked IANA zone id.(timeZone: string) => void-
zonesZone ids to offer. Defaults to every zone the browser knows (`Intl.supportedValuesOf("timeZone")`).string[]-
showCurrentTimeShow each zone's current local time in the list.booleantrue
groupByRegionGroup zones under their region (America, Europe...). When false, one list sorted by offset.booleantrue
placeholderTrigger text while nothing is selected.string"Select a time zone"
disabledDisables the trigger.boolean-
idId for the trigger, so a `<label htmlFor>` or FormField can name it.string-
nameSubmits the selected zone id under this name inside a `<form>`.string-
requiredRequires a selection before the form submits.boolean-
aria-labelAccessible name when there is no visible label. Defaults to "Time zone" when no `id` is passed.string-
classNameClasses for the trigger button (width defaults to w-72).string-

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.

Keyboard interactions

Keyboard interactions
KeyAction
EnterorSpaceorArrowDownOn the trigger, opens the list with the search field focused.
ArrowDownorArrowUpMoves the highlight through the matching zones, across region groups.
EnterSelects the highlighted zone and closes the list.
EscapeCloses 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 instead. The search field is labelled "Search time zones".

Frequently asked questions

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.

Dependencies

npm

@base-ui/reactlucide-react

Built from

No other MiniDev files

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.

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.

Plain form submit

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

All form components