Time field

TimeField edits a time of day, such as the hour a schedule starts. It shows the time the way the reader's language writes it — 9:30 AM in English, 09:30 in German and French — and splits it into parts you can step with the arrow keys, type, or replace by pasting a whole time. It always holds a valid time, so there is no empty state to validate.

import { TimeField } from '@tale/ui/time-field';
import type { TimeOfDay } from '@tale/ui/time-of-day';

Pick a time

value is a TimeOfDay: hour from 0 to 23 and minute from 0 to 59, on the wall clock. onValueChange receives the new time each time a part is committed, and only when the time changed. The field never reads a clock or a time zone; what the time means — which day, which zone — is your host's decision.

By default the field uses the hour cycle of the language the page renders in. Pass hourCycle={12} or hourCycle={24} to fix it, as the example does. On a 12-hour clock the hour reads 1 to 12 and a third part holds the day period, such as AM and PM; the stored hour is still 0 to 23. The example shows the stored value under the fields.

Name the field with label, or with aria-label or aria-labelledby when the surrounding layout already shows its name, such as From and Until beside a pair of fields.

Step, type and paste

Each part — hour, minute and, on a 12-hour clock, the day period — is a tab stop and a spin button.

The arrows never carry into the next part: stepping the minutes past 59 does not change the hour. Typing moves on as soon as a part is complete. On a 24-hour clock, 7 is 07 and moves to the minutes, while 2 waits for a second digit, because it could start 20 to 23. On a 12-hour clock, 1 waits for 10, 11 or 12. A part typed halfway is committed when you leave it, and a part you cleared and left empty returns to its last value. Typing :, . or h in the hour moves to the minutes.

Pasting a whole time into any part replaces the time: 17:30, 1730, 17h30, 17.30 and 5:30 pm all work. Anything else leaves the time unchanged, and a screen reader hears an example of what the field takes. The wheel never changes a time, so scrolling a popover over the field is safe. Escape is left to the surrounding layer, such as the popover it sits in.

Show states

description sits under the label, and errorMessage marks every part invalid and shows the message under the field. The field has no rules of its own: a time outside your range is your host's error, as in the example, where a reminder before office hours is refused.

A label or description puts the field in the standard label-and-field frame; keep them for the field's whole life. Without them, the field renders bare and an errorMessage follows it as its next sibling, so place the two in a column. An error that appears or clears while someone types never remounts the field, so focus and a part typed halfway stay where they are.

Accessibility

• The field is a group named by its label. Its description starts with the whole time as the locale writes it, then your description, error and aria-describedby, so entering the group announces the time before any help, such as "Until, 6:00 PM".
• Each part is a spin button with its own name (Hours, Minutes, AM/PM) and a spoken value: the hour as "9 PM" or "21 Uhr", the minutes as "30 minutes", the day period as its word. A cleared part reads "Empty".
• The ring around the field shows that it has focus, and the focused part is filled in the accent colour, as a pressed chip is, so you can see which part a digit goes into. The fill keeps more than 3:1 contrast against the field in both themes.
• Clicking the label focuses the hour; clicking the field's padding or separator focuses the nearest part.
• Every part is at least 24px wide and 24px tall. On a phone, a part scrolls into view when it takes focus, and the hour and minutes open the numeric keyboard.

Props

@tale/ui/time-of-day holds the helpers the field is built on: formatTimeOfDay(time, locale, cycle?) writes a time the way the locale does, localHourCycle(locale) reads a language's hour cycle, parseTimeText(text) reads a pasted time, and compareTime, sameTime and clampTime order, compare and bound times.