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.
Installation
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
import { TimezoneSelect } from "@/components/ui/timezone-select"
export function Example() {
return (
<TimezoneSelect />
)
}
API reference
| Prop | Type | Default |
|---|---|---|
| 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. | boolean | true |
| groupByRegionGroup zones under their region (America, Europe...). When false, one list sorted by offset. | boolean | true |
| 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
| Key | Action |
|---|---|
| EnterorSpaceorArrowDown | On the trigger, opens the list with the search field focused. |
| ArrowDownorArrowUp | 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 arerole="option"witharia-selected; the check icon isaria-hidden. - Without
aria-labelorid, the trigger is named "Time zone". With anid, it is named by your<label htmlFor>orFormFieldinstead. 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
Built from
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.