Timezone

Inline live clock for city names or IANA timezones.

Installation

npx shadcn@latest add @iconiq/timezone

Props

Timezone

Inline live clock that resolves friendly city names or IANA timezone strings, then animates digit changes with fluid spring rolls and pulsing separators.

zonestring

Required

City alias such as `San Francisco`, common shorthand like `NYC`, region/city IANA paths such as `Africa/Cairo`, or any of the 400+ IANA timezones from `Intl.supportedValuesOf('timeZone')`.

format"12h" | "24h"

Default "12h"

Controls whether the clock renders with a 12-hour or 24-hour display.

showAbbreviationboolean

Default true

When true, appends a timezone label after the clock.

zoneName"abbreviation" | "offset"

Default "abbreviation"

Controls the label style when `showAbbreviation` is true. `abbreviation` renders IST, EST, or PST. `offset` renders GMT-style labels such as GMT+5:30.

liveboolean

Default false

When true, updates every second and includes seconds in the formatted output.

localestring

Default "en-US"

Locale passed to `Intl.DateTimeFormat` for number and time formatting.

classNamestring

Optional class names applied to the rendered `time` element.

City aliases normalize spacing and casing, so values like `San fransico` still resolve to `America/Los_Angeles`.

All IANA timezones from the runtime environment are indexed automatically, including full paths like `Pacific/Kiritimati` and unique city slugs like `Africa/Abidjan`.

The clock uses `suppressHydrationWarning` and client-side ticking so SSR and hydration stay stable in Next.js apps.

Digit motion and zone transitions automatically disable when `prefers-reduced-motion: reduce` is enabled.

Digit rolls use transform and opacity only so Safari and other WebKit browsers avoid filter-blur compositing glitches.

The component renders a semantic `time` element with a machine-readable `dateTime` value in the target timezone.

By default the clock refreshes once per minute. Pass `live` for second-level updates in dashboards or hero copy.

Unknown zones render a compact destructive fallback label instead of throwing during render.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: motion.