Time dialPro

• Type: Component (special)
• Access: Xzero Pro
• Page: https://ui.xzero.co.uk/components/time-dial
• Markdown: https://ui.xzero.co.uk/components/time-dial/markdown
• Source file: registry/components/time-dial/time-dial.tsx
• Dependencies: motion, lucide-react
• Keywords: special, motion, react time zone picker, world clock dial, meeting time planner, timezone converter ui, rotary time picker, time zone dial

When to use

• Planning a moment across two to five cities, such as calls, releases, or handovers.
• Distributed teams that need to see at a glance who is inside working hours.

When not to use

• Use time-picker for a single local time.
• Use date-picker or calendar when the day matters more than the hour.
• Use slider for a plain numeric range.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/time-dial

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useState } from "react";
import { TimeDial } from "@/components/xzero/time-dial/time-dial";

const cities = [
  { id: "nyc", name: "New York", code: "NYC", offset: -240 },
  { id: "lon", name: "London", code: "LON", offset: 60 },
  { id: "tyo", name: "Tokyo", code: "TYO", offset: 540 },
];

export function CallPlanner() {
  const [time, setTime] = useState(15 * 60);
  return <TimeDial cities={cities} value={time} onValueChange={setTime} hourCycle={24} workingHours={[480, 1020]} label="Call time" />;
}

API reference

TimeDial

A 24 hour rotary dial for choosing a time across time zones. Every city rides the dial at its own local time, a shaded band marks working hours, and the home city reads out in the center.

Prop	Type	Default	Description
cities (required)	{ id: string; name: string; code: string; offset: number }[]	–	Two to five cities. offset is minutes from UTC in steps of 15; code is two or three letters shown on the dial.
value	number	–	Controlled time in UTC minutes from midnight on the reference day. May leave 0 to 1439 to reach adjacent days.
defaultValue	number	0	Initial time when uncontrolled.
onValueChange	(value: number) => void	–	Fires with the destination as soon as the dial is released or stepped, before it comes to rest.
homeId	string	–	Controlled id of the city the dial reads in. Defaults to the first city.
defaultHomeId	string	–	Initial home city when uncontrolled.
onHomeChange	(id: string) => void	–	Called when a city is chosen from the list.
min	number	-Infinity	Earliest time in UTC minutes. The dial stretches past it and springs back.
max	number	Infinity	Latest time in UTC minutes.
weekday	number	1	Weekday of the reference day in UTC, 0 for Sunday.
hourCycle	12 | 24	12	Clock for the readout: 12 reads 9:30 AM, 24 reads 09:30.
workingHours	[start: number, end: number]	[540, 1080]	Local working hours in minutes from midnight, drawn as a band on the dial. A city inside the band is at work. Defaults to 9:00 to 18:00.
label	string	"Time"	Accessible name of the dial.
className	string	–	Class on the root element.

Keyboard interactions

Keys	Action
Arrow Right / Arrow Up	Step forward a quarter hour.
Arrow Left / Arrow Down	Step back a quarter hour.
Page Up / Page Down	Step an hour forward or back.
Home / End	Jump to the start or last quarter hour of the home city's day.

Accessibility

• The dial is a focusable role="slider" with aria-valuenow in home-city minutes and a spoken aria-valuetext.
• The city list uses buttons with aria-pressed for the home city.
• Changes are announced through a polite live region; the SVG face and readout are aria-hidden.

Motion

• Drags have soft quarter-hour detents, flicks coast on a spring into the nearest quarter hour, and bounds rubber-band.
• Readout digits roll like an odometer, city marks swap between knob and dot as the home city changes, and the sun and moon turn over at the day/night boundary.
• Reduced motion removes flick coasting and replaces rises and blurs with plain fades.

Responsive behavior

• The root is a container up to 720px; from 600px the dial and city list sit side by side, below that they stack.
• The dial is min(100%, 256px) with touch-action none, so dragging it on touch never scrolls the page.
• Below 360px of container width the city rows tighten.

Performance

• The face is one SVG and rotation runs on motion values, so drags do not re-render city rows.
• Offsets are fixed per city; there is no time zone database, so pass DST-correct offsets yourself.

Notes for AI

• Use to plan a moment across two to five offices (calls, releases, handovers). For a single local time use time-picker.
• Store the value in UTC minutes and convert per city yourself; offsets are fixed, so pass DST-correct offsets for the date in question.
• Set workingHours to the team's shared day so the band shows at a glance who would be at work, and hourCycle to match the locale.

Related

• Time picker: Choose a time with sensible keyboard behavior.
• Date picker: Choose a date without losing context.
• Calendar: Browse dates in a clear, compact month view.
• Slider: Pick a value or a range on a track that follows your finger.

Also in data

• Booking pill: One pill that reshapes through party size, date, time, and a ticket.
• Activity rings: Daily goals as tick rings that sweep, count up, and trace a second lap past 100%.
• Date reel: A 3D wheel date and time picker (like iOS reels) with momentum scrolling, snapping, curved perspective, and full keyboard support.

Guidance for AI tools

Time dial: Spin a dial to pick an hour and see which team cities are at work. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt