# Time Zone Select

> A time zone picker with cities instead of IANA ids. Each row shows its live local time, current GMT offset, a day or night glyph and the weekday when it's already tomorrow there. Your own zone is pinned on top (or preselected with "auto"), and search takes cities, countries, abbreviations like PST or IST, and offsets like +5:30. Matches every other select.

- Slug: `timezone-select`
- Category: [Selects](https://www.assembli.design/category/selects.md)
- Type: component
- Tags: timezone, time-zone, select, combobox, search, intl, clock, scheduling
- npm dependencies: @base-ui/react, lucide-react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/timezone-select
- Page: https://www.assembli.design/components/timezone-select

![Time Zone Select preview](https://www.assembli.design/thumbnails/timezone-select-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string \| null` |  | IANA name. Pass with `onValueChange` to control it. |
| `defaultValue` | `string \| null` | `null` | IANA name, or `"auto"` for the reader's own zone once the page loads. |
| `onValueChange` | `(value: string \| null, zone: TimeZoneOption \| null) => void` |  |  |
| `zones` | `TimeZoneGroup[]` | `TIME_ZONES` | Your own list. Defaults to `TIME_ZONES`. |
| `showDetected` | `boolean` | `true` | Pins the reader's zone in a "Your time zone" group at the top. Defaults to `true`. |
| `hourCycle` | `"h12" \| "h23"` |  | `"h12"` for 9:42 PM, `"h23"` for 21:42. Defaults to the locale's habit. |
| `locale` | `string` |  |  |
| `label` | `React.ReactNode` |  |  |
| `hint` | `React.ReactNode` |  | Quiet text to the right of the label, such as "Optional". |
| `description` | `React.ReactNode` |  |  |
| `error` | `React.ReactNode` |  | Replaces the description and marks the trigger `aria-invalid`. |
| `placeholder` | `React.ReactNode` | `"Select a time zone…"` |  |
| `size` | `SelectSize` | `"md"` |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `name` | `string` |  | Submits the IANA name with a surrounding form. |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `triggerClassName` | `string` |  | Classes for the trigger; `className` goes on the root. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/timezone-select/timezone-select.tsx` and installs dependencies):

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

Registry item JSON: https://www.assembli.design/r/timezone-select.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.