createTimePicker API
Related
Explore these related pages for additional context and usage patterns.
| Page | Category |
|---|---|
| createTimePicker | Forms |
| Time Picker | Forms |
| createNumeric | Forms |
Functions
Options
formNamespace
string | undefinedForm injection key. Must match the parent Form's namespace.
Default: 'v0:form'
required
boolean | undefinedWhether required. When true, a presence rule is registered so Form
submit fails on empty values even with novalidate.
errorMessages
MaybeRefOrGetter<MaybeArray<string> | undefined>Manual error messages — merged with rule-based errors.
value
Ref<string | null, string | null> | undefinedCanonical HH:mm or HH:mm:ss source. The picker snaps an incoming
value to the step grid, moves it to the nearest on-grid time inside
min / max when it falls outside them, and writes it back in
canonical form. With seconds on, HH:mm reads as second 0; with
it off, HH:mm:ss drops the seconds. An unparseable value empties the
fields and becomes null. That pass runs before the next flush,
together with any option that changed in the same tick; until then the
fields show the value as written.
The model has the last word. When, after its owner has had a tick to
answer, it does not hold the value the picker wrote, the fields take
the model's value as given and the picker writes nothing further. The
picker treats an owner that answers later than that the same way until
its value arrives.
Default: shallowRef(null)
hourCycle
MaybeRefOrGetter<TimeHourCycle | undefined>h12 shows 1–12 and a meridiem. h23 shows 0–23.
The picker reads any other value as h23.
Default: 'h23'
seconds
MaybeRefOrGetter<boolean> | undefinedInclude seconds in the canonical value. Turning it on for a picker whose
hour and minute have values keeps the time and sets the second to 0.
Turning it off drops the second.
Default: false
hourStep
MaybeRefOrGetter<number | undefined>Hour interval. The hour moves on the multiples of the step inside
0–23; in h12, on those inside the current meridiem's half of the
day. Fractions truncate, and the picker reads a non-finite or
non-positive step as 1. A half with no multiple of the step holds its
first hour only.
Default: 1
minuteStep
MaybeRefOrGetter<number | undefined>Minute interval. The minute moves on the multiples of the step inside
0–59. Fractions truncate, and the picker reads a non-finite or
non-positive step as 1. A step above 59 leaves 0 as the only
minute.
Default: 1
min
MaybeRefOrGetter<string | null | undefined>Inclusive lower bound, HH:mm or HH:mm:ss. Applies to a complete
value only. A value below it moves to the earliest time at or after
min that is on every field's step grid; with minuteStep: 15,
min: '10:07' starts the range at 10:15. Only when no on-grid time
lies between min and max does the picker set the grid aside and
clamp the value to the bound itself. The picker ignores the bound's
seconds while seconds is off, so min: '09:00:30' then admits
09:00. The picker ignores an unparseable min and keeps max; a
min above max, by the same comparison, turns both bounds off.
max
MaybeRefOrGetter<string | null | undefined>Inclusive upper bound, HH:mm or HH:mm:ss. Applies to a complete
value only. A value above it moves to the latest time at or before
max that is on every field's step grid; with minuteStep: 15,
max: '17:10' ends the range at 17:00. Only when no on-grid time
lies between min and max does the picker set the grid aside and
clamp the value to the bound itself. The picker ignores the bound's
seconds while seconds is off, so max: '17:00:30' then stops at
17:00. The picker ignores an unparseable max and keeps min; a
max below min, by the same comparison, turns both bounds off.
Properties
value
Ref<string | null, string | null>Canonical 24-hour value, or null while a field is still empty.
Writing it from outside replaces every field at once; the picker
normalizes it before the next flush. The picker writes it only when
an edit changes the time, and never while disabled or readonly.
hour
Readonly<Ref<number | null, number | null>>Field hour. 0–23 in h23, 1–12 in h12. null when unset.
second
Readonly<Ref<number | null, number | null>>Second field, or null when seconds are off or unset.
period
Readonly<Ref<TimePeriod | null, TimePeriod | null>>Meridiem. null in h23. In h12 with an empty hour, the meridiem
the picker remembers: the last one you set with commit or step,
the one the hour had when you cleared it, or the one of the last
incoming value. clear() and an incoming null, '', or
unparseable value reset it to 'am'.
display
Readonly<Ref<string | null, string | null>>The time the fields show, as the canonical string, or null while a
field is empty. It matches value except in two cases.
The model holds a string the fields cannot show as written, and the
picker has not rewritten it: because it is disabled or readonly,
because it took the owner's value as given after a refused write, or
because the value came in during this tick and the pass has not run
yet. That is a string that is not a time, where display is null,
or a time whose seconds do not match the seconds option, where
display adds :00 or leaves the seconds out.
The picker wrote a value the model does not hold yet. display runs
ahead of value until the picker checks the answer one tick later,
whether the owner answers late or refuses.
input
InputContext<string | null>The underlying createInput context: validation state, the ARIA ids,
focused and touched, and validate / reset. The picker validates
the model value, so required fails while a field is still empty.
Normalizing is not an edit: a value the picker snapped or bounded is
still pristine, unless the picker built it from edited fields.
reset puts the initial value back, drops a partly entered time, and
clears the validation state and isTouched. While disabled or readonly
it does all of that except write the model. isPristine reads true
after a reset even when the model does not take the initial value
back, because the picker is disabled or readonly and writes nothing,
or because the owner refuses the write. reset does not count toward
revision, except while error or errorMessages is set.
The picker reads required and rules once, at creation.
revision
Readonly<Ref<number, number>>Goes up when the model holds a new settled value worth validating.
Watch it to validate on input.
An edit the owner took counts, and so does a value from outside. The
picker normalizing on its own counts only once the value already has
a validity: input.isValid is not null. input.reset() does not
count, except while error or errorMessages is set, which keep a
validity through the reset.
An owner that answers late (see the value option) hands the
picker's own normalizing write back as a value from outside, and
that counts. An initial value that needs normalizing then counts at
creation, and again after a reset.
Methods
commit
((part: TimeUnit, value: number | null) => void) & ((part: "period", value: TimePeriod) => void)Set one field. null clears a numeric field and the value becomes
null. The picker holds a number inside the field's range and snaps
it to the nearest grid point without wrapping. In h12 it reads the
hour as a display hour in the current meridiem. A period commit moves
a set hour to the other half of the day, and the picker remembers it
while the hour is empty.
The edit works on what the fields show. The picker first applies a
value or option that changed earlier in the same tick, but not a value
the fields took as given after a refused write. The edited field
follows the rules above, then the picker normalizes the whole time and
writes it once.
It writes nothing for period in h23, for the period already shown,
for second while seconds are off, for null on an empty field, and
for a non-finite number, unless a change from the same tick was still
waiting, which it then publishes.
step
(part: TimePart, count?: number) => voidMove one field along its grid. The sign of count is the direction and
its magnitude the number of intervals; it defaults to 1, fractions
truncate, and 0 or a non-finite count does nothing. The field wraps
past either end, and a value off the grid first moves onto the adjacent
grid point. An h12 hour stays inside its meridiem. An empty field
lands on its first grid point, whatever the count: 0 for a minute, a
second, or an h23 hour, and the first hour of the remembered meridiem
for an h12 hour, which is 12 with the default step. Any non-zero
count flips the period.
The step starts from what the field shows, so a value the fields took
as given after a refused write moves onto the adjacent grid point in
the direction of travel. The picker first applies a value or option
that changed earlier in the same tick. It then normalizes the whole
time and writes it once. A count of 0, a non-finite count, period
in h23, and second while seconds are off write nothing, unless a
change from the same tick was still waiting, which the picker then
publishes.
grid
(part: TimeUnit) => TimeGridLowest and highest grid values of a numeric field, plus its resolved
step. An h12 hour reports display hours for the current meridiem.