Time fields

Code

import { TimeField, TimeZoneField } from "@fadymondy/nasaq/web";import { useState } from "react";export function Reminder() {  const [time, setTime] = useState<string | null>("09:00");  const [zone, setZone] = useState("Asia/Riyadh");  return (    <div className="flex max-w-sm flex-col gap-3">      <TimeField value={time} onValueChange={setTime} aria-label="Remind me at" />      <TimeZoneField value={zone} onValueChange={setZone} />    </div>  );}

Pickers · beta

Live examples and controls: Time fields in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/time-fields.json

Four controls for the time of day and the place it is read in.

Values are plain strings: "09:30" for a time and an IANA name such as "Asia/Riyadh" for a zone. They store, sort and travel in JSON without translation.

When to useCopy Anchor Link

• Opening hours, shifts, quiet hours, reminders and any form where people know the time they want and can type it.
• Account or workspace settings that need a time zone, and meeting tools that compare zones.

When not to useCopy Anchor Link

• Choosing a date, or a date with a time: use DatePicker.
• The period a dashboard covers: use TimeRangePicker.
• A duration ("2 hours"): use a number field with a unit.

ImportCopy Anchor Link

import { TimeField, TimeSpanField, TimeZoneClock, TimeZoneField, parseTimeInput, convertWallTime } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

import { TimeField, TimeZoneField } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Reminder() {
  const [time, setTime] = useState<string | null>("09:00");
  const [zone, setZone] = useState("Asia/Riyadh");
  return (
    <div className="flex max-w-sm flex-col gap-3">
      <TimeField value={time} onValueChange={setTime} aria-label="Remind me at" />
      <TimeZoneField value={zone} onValueChange={setZone} />
    </div>
  );
}

AnatomyCopy Anchor Link

TimeField        data-slot="time-field"        Input (ltr) + "Will be 09:30" preview or error + hidden input when `name`
TimeSpanField    data-slot="time-span-field"   two TimeFields, an arrow, the duration and an "overnight" badge
TimeZoneClock    data-slot="time-zone-clock"   city, ticking time, date, offset, difference from `reference`
TimeZoneField    data-slot="time-zone-field"   Combobox (search + zone rows with live clocks) + "Use my time zone" + TimeZoneClock

APICopy Anchor Link

TimeFieldCopy Anchor Link

TimeSpanFieldCopy Anchor Link

value / defaultValue / onValueChange with { start, end }, plus allowOvernight, showDuration (default true), step, min, max, disabled, labels.

TimeZoneClockCopy Anchor Link

TimeZoneFieldCopy Anchor Link

Helpers (pure, no React)Copy Anchor Link

ExamplesCopy Anchor Link

Opening hours, with a night shift:

import { TimeSpanField } from "@fadymondy/nasaq/web";

export const Shift = () => <TimeSpanField defaultValue={{ start: "22:00", end: "06:00" }} allowOvernight />;

A world clock strip:

import { TimeZoneClock } from "@fadymondy/nasaq/web";

export const Strip = () => (
  <div className="grid gap-3 sm:grid-cols-3">
    {["Asia/Riyadh", "Europe/London", "America/New_York"].map((z) => <TimeZoneClock key={z} timeZone={z} reference="Asia/Riyadh" />)}
  </div>
);

AccessibilityCopy Anchor Link

Errors and the preview are linked to the input with aria-describedby; the field is marked invalid when the text is refused. Clocks are role="timer" with aria-live="off" so they do not chatter; the accessible name has the city, the time and the date.

RTL & i18nCopy Anchor Link

• Times, offsets and zone names are isolated left-to-right (dir="ltr", <bdi>) inside Arabic text, and digits are Latin in both languages.
• The field accepts Arabic-Indic (٠٩٣٠) and Persian digits and the Arabic am / pm markers.
• The span arrow mirrors. City names come from the zone id; the long zone name is localised by Intl.

Styling & tokensCopy Anchor Link

Uses Input, Combobox, Badge and Button tokens. Target the data-slot values above; extend with className.

Do / Don'tCopy Anchor Link

• Do store the "HH:mm" string and the IANA zone name, not an offset. Offsets change with daylight saving.
• Do pass now in stories and tests so the clock does not move.
• Don't use TimeField for a duration or for a time that includes a date.
• Don't ship your own zone list unless you need to narrow the choices; pass zones for that.

RelatedCopy Anchor Link

• DatePicker
• TimeRangePicker
• Field

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-pickers-time-fields--docs