All components (204)
Time
Dates and time · TimeField
What it is and when to use it
A time written in parts, like the date field: the hour and minutes (and the seconds or AM/PM if needed) are segments that are typed with numbers or raised and lowered with the arrows, without opening anything and without being able to type 25:70. The values are TimeValue objects ({ hour, minute, second }, the hour from 0 to 23 always), not strings.
When to use it
- The time of an appointment, a pickup, a scheduled shipment.
granularity="second"for short durations or timestamps;"hour"if only the hour on the dot counts.backfor what accompanies the time: a zone ("CET"), a small button.icon={false}removes the clock.hiddenLabelin a grid of times where the column name is already written once above.nameso the time travels in a native form.
When not to
- The day:
DatePicker. If both are needed, they go in two fields, side by side. - A business's opening hours, day by day and by time slots:
WeeklySchedule. - Choosing among free slots of a calendar:
SlotPicker.
Keyboard: each segment is a Tab stop, and Left Arrow and Right Arrow also move from one to another. Up and Down raise and lower only the segment with focus, not the whole time; Home and End take it to its ends; the number is typed directly and Backspace deletes it.
Accessibility: the label is required and names the group; with hiddenLabel it is hidden from view, never from the reader. The help is linked to the group. With error, each segment is marked as invalid and carries the message as its description, which is where the focus is. The clock is decoration.
Fine-tuning: CSS variables of the box, those of all fields: --amset-field-height, -padding, -font, -label, -description, -radius, -background and -border. The segments and the clock are those of the date field, and are adjusted with the same variables: --amset-date-target and --amset-date-icon. A date and a time placed side by side look the same.
Context: it goes inside LocaleProvider (or AmsetProvider). The language decides whether it is 12 or 24 hours: in es-ES, 24; cycle forces it.
What it looks like
<TimeField label="Pickup time" defaultValue={{ hour: 10, minute: 30, second: 0 }} hint="From 10:00 to 20:00" />
<TimeField label="Appointment time" defaultValue={{ hour: 20, minute: 45, second: 0 }} error="The store closes at 8:00 pm" />Props
Import it with import { TimeField } from '@amset/ui'. Required props are marked.
| Prop | Type | What it does |
|---|---|---|
labelrequired | string | Required: a field without a visible label does not get into the library. |
back | ReactNode | Content after the time: a zone ("CET"), a button. |
className | string | — |
cycle | 12 | 24 | 12 or 24 hours. Without it the language decides (`es-ES` is 24), which is right in practice: forcing 12 in Spanish makes people read "PM". |
defaultValue | T | null | The time at the start, without controlling it from outside. |
disabled | boolean | — |
error | string | Error message. When it is passed, the field is marked as invalid. |
granularity | TimeGranularity | Defaults to `minute`: a bare hour is almost never what is asked for. |
hiddenLabel | boolean | Hides the label from view, never from the reader. For a grid of times where the column name is already written once above. |
hint | string | — |
icon | boolean | Clock in front of the segments. On, because a time field without a clock is not recognized. |
invalid | boolean | — |
name | string | So the time travels in a native form. |
onChange | (value: PlainTime) => void | It only notifies with a WHOLE time: half a time is not a value, so whoever listens does not have to filter half-finished states. |
placeholderValue | PlainTime | What time an EMPTY segment starts from when touched with an arrow. Without it, from midnight. With it, from wherever makes sense: in a field for appointments that start at nine, going up hour by hour from 0:00 is work nobody should have to do. It is not a value: the field stays empty until it is touched, and what is sent is still nothing. For an initial value there is `defaultValue`. |
readOnly | boolean | — |
required | boolean | — |
shouldForceLeadingZeros | boolean | Leading zeros in the hour. On by default, which is what is expected of a time field: "09:05" and not "9:05". |
size | "sm" | "md" | "lg" | — |
validationBehavior | "aria" | "native" | `aria` (the default) announces the state without the browser interrupting submission with its bubble; `native` also adds its own validation. |
value | T | null | The time, controlled from outside. |
variant | FieldVariant | — |
It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.
In the test bench
Every state and variant, to try one at a time, on its page at ui.amset.tech: