Timezone Select React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Pro item: the CLI needs a Pro account. See plans

Usage

Import TimeZoneSelect from @/components/ui/timezone-select.

import { useState } from "react"
import { Globe } from "lucide-react"
import { TimeZoneSelect } from "@/components/ui/timezone-select"

export function ProfileTimeZone() {
  const [timeZone, setTimeZone] = useState("America/New_York")
  return (
    <TimeZoneSelect
      label="Time zone"
      description="Used for reminders and weekly reports."
      leftIcon={<Globe />}
      value={timeZone}
      onValueChange={setTimeZone}
      suggested={["America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles"]}
      suggestedLabel="United States"
      showTime
      name="timeZone"
    />
  )
}

Props

• labeldefault ""
  ReactNode

  The label above the field; it also names the list and the phone sheet.

• descriptiondefault ""
  ReactNode

  Helper text under the field, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with an error and marks the field invalid.

• requireddefault false
  boolean

  Adds the asterisk to the label and required to the input.

• invaliddefault false
  boolean

  The invalid look without a message.

• disableddefault false
  boolean

  Dims the field and blocks it.

• readOnlydefault false
  boolean

  Shows the zone without letting anyone change it.

• value
  string

  The chosen IANA id, like "America/New_York", when you control it. Older ids ("Asia/Calcutta", "Europe/Kiev") are read as their current names.

• defaultValuedefault ""
  string

  The starting zone, uncontrolled. "" is empty.

• onValueChange
  (value: string) => void

  Called with the IANA id of the picked zone (the browser's zone for the Use my time zone row).

• timeZones
  string[]

  The zones to offer. Default: every zone the browser knows (Intl.supportedValuesOf), with UTC added, or a built-in list of about 55 common zones on older runtimes.

• groupBydefault "region"
  "region" | "offset" | "none"

  region groups by the id's continent (Americas, Europe, Asia...) sorted by city; offset groups by UTC offset from west to east; none is one flat list from west to east.

• showOffsetdefault true
  boolean

  The UTC offset at the end of each row, like "UTC−04:00". Grouping by offset puts it in the group titles instead.

• showTimedefault false
  boolean

  The current local time in each row, refreshed every minute while the list is open.

• formatdefault "long"
  "long" | "short"

  long puts the zone name under the city in each row ("Eastern Daylight Time"); short shows the city only. The name stays searchable either way, and the field always shows the city.

• suggested
  string[]

  Zones listed first under suggestedLabel, like the ones your team uses. They move out of their region group.

• suggestedLabeldefault "Suggested"
  string

  The title of the suggested group.

• detectdefault true
  boolean

  Adds a first row that picks the browser's own time zone, when it is in the list.

• detectLabeldefault "Use my time zone"
  string

  The text of the detect row; the detected zone shows under it.

• date
  Date

  The instant used for offsets, names and times, so daylight saving time is right for a meeting next month. Default: now.

• localedefault ""
  string

  Locale for zone names and times through Intl. Falls back to the UIProvider locale, then to the browser's. City names stay as in the IANA id.

• regionLabels
  Partial<Record<string, string>>

  Group titles keyed by the id's first part: America, Europe, Africa, Asia, Australia, Pacific, Atlantic, Indian, Antarctica, Arctic and Other (UTC). Defaults in TIME_ZONE_REGION_LABELS.

• placeholderdefault "Select a time zone"
  string

  Shown while the field is empty, also in the phone sheet's search box.

• emptyTextdefault "No time zones found"
  string

  Shown when the search matches nothing.

• clearabledefault false
  boolean

  An x while a zone is chosen; Escape on a closed list clears too.

• clearLabeldefault "Clear"
  string

  The accessible name of the x button.

• toggleLabeldefault "Show time zones"
  string

  The accessible name of the chevron button.

• openOnFocusdefault true
  boolean

  Opens the full list as soon as the field gets focus, and again on a click, like a select. Off: the list opens when you type, press ArrowDown or use the chevron.

• autoHighlightdefault true
  boolean

  The first match is highlighted while you search, so Enter picks it.

• highlightMatchesdefault true
  boolean

  The matched letters of each zone in bold.

• fuzzydefault false
  boolean

  Also matches letters in order with gaps ("lsa" finds Los Angeles), ranked last.

• leftIcon
  ReactNode

  An icon before the text, like a Globe. Unsized svgs follow the size.

• sizedefault "md"
  "sm" | "md" | "lg"

  32 / 40 / 48px like every field; md grows to 44px on touch screens.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The box: a filled well, an outline, a bottom line, or nothing until hover.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled per size like the button (md is 8 / 10 / 12px).

• defaultOpendefault false
  boolean

  Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.

• open
  boolean

  Whether the list is open, controlled.

• onOpenChange
  (open: boolean) => void

  Called when the list opens or closes.

• responsivedefault true
  boolean

  Below 768px the field opens a full-height search sheet instead of the popover.

• sheetTitledefault "Time zone"
  string

  The phone sheet's title for screen readers (its visible header is the search box); a string label wins.

• cancelLabeldefault "Cancel"
  string

  The text button next to the sheet's search box.

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the list opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  How the list lines up with the field.

• maxHeightdefault 360
  number

  The list's height limit in px, capped by the room on screen.

• virtualThresholddefault 100
  number

  Above this many rows only the visible ones render (the full list has about 420).

• renderOption
  (option, state: { selected, highlighted, disabled, ranges }) => ReactNode

  Replaces a row's content; the row element, its aria and its classes stay.

• namedefault ""
  string

  Submits the IANA id through a hidden input.

• id
  string

  The input's id; generated when left out.

• onChange
  (event: ChangeEvent<HTMLInputElement>) => void

  The native event of every keystroke in the search, untouched.

• container
  HTMLElement | null

  Portal target for the list and the sheet (default document.body).

• fieldProps
  Partial<FieldProps>

  Anything else for the field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "input" | "leftIcon" | "spinner" | "clear" | "toggle" | "content" | "list" | "item" | "group" | "status" | "sheet" | "sheetSearch" | "cancel", string>>

  Extra classes for the inner parts, the same slots as the Combobox. content is the popover, sheet the phone sheet.

• className
  string

  Extra classes for the outermost element: the Field when there is a label or message, else the combobox root.

• ref
  Ref<HTMLInputElement> (a useRef object or an (el) => void callback)

  The search input. Other input props (onBlur, onKeyDown, autoFocus, aria-*, data-*) land on it too.

Parts

FAQ

More React input components