createTimePicker
Keep a time as separate hour, minute, and optional second fields. The public value stays null until every enabled field has a number.
Usage
Call createTimePicker inside a component setup or an effectScope. Its watchers belong to the scope that is active at the call, and stopping that scope disposes the picker. When you call it at module level, as in the block above, the watchers live for the life of the page.
Architecture
createTimePicker owns the fields and the canonical string. It reads no DOM, window, or date plugin, and reports bad input through useLogger. Validation, field state, and form registration come from createInput. TimePicker builds its spinbuttons on the returned context.
Options
| Option | Type | Default | Notes |
|---|---|---|---|
value | Ref<string | null> | shallowRef(null) | Canonical 24-hour string, or null. The picker writes normalized values back to it |
hourCycle | MaybeRefOrGetter<TimeHourCycle | undefined> | 'h23' | 'h12' shows 1–12 and a period. The picker reads any other value as 'h23' |
seconds | MaybeRefOrGetter<boolean> | false | When true, the string includes seconds |
hourStep | MaybeRefOrGetter<number | undefined> | 1 | Hour interval |
minuteStep | MaybeRefOrGetter<number | undefined> | 1 | Minute interval |
secondStep | MaybeRefOrGetter<number | undefined> | 1 | Second interval |
min | MaybeRefOrGetter<string | null | undefined> | — | Inclusive lower bound, HH:mm or HH:mm:ss |
max | MaybeRefOrGetter<string | null | undefined> | — | Inclusive upper bound, same form as min |
disabled | MaybeRefOrGetter<boolean> | false | Blocks every edit and every write to value |
readonly | MaybeRefOrGetter<boolean> | false | Blocks every edit and every write to value |
required | boolean | — | Fail validation while the value is null |
rules | (FormValidationRule | RuleAlias | StandardSchemaV1)[] | [] | Validation rules. Each receives the value |
error | MaybeRefOrGetter<boolean> | false | Force the invalid state |
errorMessages | MaybeRefOrGetter<MaybeArray<string> | undefined> | — | Messages that come before the ones the rules produce |
id, label, name, form | string | — | The picker passes them to input for the markup that renders the field |
formNamespace | string | 'v0:form' | Namespace of the parent form to register with |
A change to hourCycle, seconds, a step, or a bound re-applies the step and the bounds to the current value before the next flush.
Step grid
Each field moves on the multiples of its step. The picker counts them from 0 on the stored 24-hour value: hours inside 0–23, minutes and seconds inside 0–59. minuteStep: 15 allows 0, 15, 30, and 45.
stepmoves along the multiples and wraps at either end. WithminuteStep: 15, stepping up from 0 gives 15, 30, 45, 0, and stepping down gives 45, 30, 15, 0.commitgoes to the nearest multiple and never wraps.commit('minute', 58)is 45.A fractional step truncates. The picker reads a non-finite or non-positive step as 1. A minute or second step above 59, or an
h23hour step above 23, leaves 0 as the field’s only value.In
h12the hour stays inside the current half of the day. The picker still counts the multiples on the 24-hour value, sohourStep: 5allows 12, 5, and 10 in the morning and 3 and 8 in the afternoon. A half of the day that holds no multiple keeps its first hour, sohourStep: 24allows 12 AM and 12 PM.
grid(part) returns the lowest and highest value a numeric field can show and its resolved step, in display values. An h12 hour reports the range for the current period. grid and the numeric form of commit take a TimeUnit, which is 'hour' | 'minute' | 'second'. step takes a TimePart, which adds 'period'.
Step count
step(part, count) takes a signed count. The sign is the direction and the magnitude is the number of intervals. The count defaults to 1 and a fractional count truncates. A count of 0 or a non-finite count changes nothing. A field that sits off its multiples moves to the adjacent multiple in the direction of travel on the first interval.
An empty field lands on its first multiple, whatever the count: 0 for a minute, a second, or an h23 hour. An empty h12 hour lands on the first hour of the remembered period, which is 12 with the default step. For period, any non-zero count toggles AM and PM.
Incoming values
A string that reaches value from outside replaces every field. The picker moves each field to its nearest multiple, brings a complete time inside min and max, and writes the result back in canonical form.
createTimePicker normalizes the initial value before it returns. For a later write the pass runs before the next flush, not inside the assignment. The fields show the incoming value as written until then, so await nextTick() before reading the normalized value. The picker applies a value and an option that change in the same tick together, so the new options judge the new value.
Edits
commit and step work on what the fields show. The edited field snaps or steps by the rules above, then the picker normalizes the whole time and writes it once.
The picker first applies a value or an option that changed earlier in the same tick, so an edit in the same tick as a change gives the same result as one a tick later.
The picker does not normalize a value the fields took as given after a refused update before the edit. With
minuteStep: 15and fields showing04:50,step('minute', -1)gives04:45.A call that changes nothing writes nothing: a zero or non-finite count, the period the hour is already in,
periodinh23,secondwhilesecondsis off, a non-finite number, or clearing a field that is already empty. If a same-tick change was waiting, the picker still publishes that change.A period commit snaps the hour to the nearest multiple inside its new half of the day.
When the model’s setter throws, the error propagates to the caller and the fields return to what they held before that call. A half-entered time keeps the fields earlier calls set: with the hour at 9 and the minute empty, a
commit('minute', 30)that throws leaves the hour at 9 and the minute empty.
| Incoming | Result |
|---|---|
'09:50' with minuteStep: 15 | '09:45' |
'09:30' with seconds on | '09:30:00' |
'09:30:15' with seconds off | '09:30' |
null or '' | Fields empty, value null |
Anything else, such as '9:30' or '25:00' | Fields empty, value null, and a development warning |
Turning seconds on while the hour and the minute have values keeps the time and sets the second to 0. A second you enter through commit or step is different: with seconds on, the value stays null until the second has a value.
Refused updates
The model has the last word. A plain ref always takes what the picker writes. A writable computed, or a component model whose parent decides, may not.
Refused. When the model does not hold what the picker wrote, the fields take the model’s value as given, and the picker applies neither the step nor the bounds and writes nothing more. The check runs one tick after the post flush, so the fields and
displaysettle within two ticks:await nextTick()twice. Rendered output that reads them follows one render later. The check never runs after the scope stops.Replaced. When the owner answers a write with a different value, the picker treats that value as an incoming one: it normalizes it and writes it back once. If the owner alters that write too, the picker takes the owner’s value as given and stops.
One edit costs at most two writes, whatever the owner does. The picker never retries a write.
Creation follows the same rule. Normalizing the initial value is one synchronous write. When an owner replaces it with a different value, the picker normalizes that replacement and writes it back once, a tick later, so creation can cost two writes. An owner that only refuses gets one.
Three things follow:
An owner should accept or refuse synchronously. One that accepts late, after a timer, a debounce, or an awaited request, looks like a refusal until its value arrives. The fields show the old model value in between, and each rapid edit starts from it. Bind the picker to a local ref and debounce or validate downstream of that ref.
An owner that rounds or transforms should give the picker the same step. A setter that rounds to 30 minutes over the default
minuteStepreceives09:01fromstep('minute')and maps it straight back to09:00, every time. WithminuteStep: 30the picker writes09:30.An edit made before the picker has checked the owner’s answer starts from the value the picker just wrote, not from the model. Several
steporcommitcalls in a row, or a test that dispatches key events without waiting, can therefore end on a different time than the same edits made one at a time when the owner refuses, caps, or rounds. Wait two ticks between programmatic edits when the owner may refuse. Real key presses arrive as separate tasks, so this does not affect them.
display is the time the fields show, as the canonical string, or null while a field is empty. It matches value except when 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, or because the value came in during this tick and the picker has not normalized it 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. display also runs ahead of value after a write the model does not hold straight away, until the picker checks the answer. That is the case under an owner that answers late, and under any owner that refuses, between the write and the check.
Bounds
min and max apply to a complete value only. A value below min moves to the earliest time at or after min that is on every field’s step. A value above max moves to the latest such time at or before max. With minuteStep: 15, min: '10:07' starts the range at 10:15, and max: '17:10' ends it at 17:00.
Only when no on-step time lies between the bounds does the picker set the step aside. It then clamps the value to the bound itself. minuteStep: 15 with min: '10:05' and max: '10:10' is such a range.
The picker ignores a bound that does not parse, and only that bound. When both parse and min is later than max, neither applies. Seconds in a bound count only when seconds is on.
Disabled and readonly
While disabled or readonly is true, commit, step, and clear do nothing, and the picker never writes value. That holds at creation, when value changes from outside, when an option changes, and for input.reset(). The fields show an incoming value as given, the picker applies neither the step nor the bounds, and the model keeps the string it received. When the picker is editable again it applies both and writes the result.
Validation
The picker composes createInput and returns it as input. It validates the model value: the 24-hour string, or null while a field is empty. With required, validation fails until every enabled field has a value. Each rule in rules receives the value and returns true or a message. Inside a component under a Form, the picker registers with it, and the form’s submit validates it.
import { createTimePicker } from '@vuetify/v0'
const time = createTimePicker({
required: true,
rules: [value => value !== '12:00' || 'Closed at noon'],
})
time.commit('hour', 12)
await time.input.validate() // false, the minute is still empty
time.commit('minute', 0)
await time.input.validate() // false
time.input.errors.value // ['Closed at noon']The picker never validates on its own. Call input.validate() when your markup decides to, and set input.isFocused and input.isTouched from it.
Normalizing is not an edit. input.isPristine stays true when the picker moves the initial value onto the step or inside the bounds, and turns false on the first edit or the first different value from outside. A time the picker completes from edited fields, such as an entered hour and minute once seconds turns off, is not pristine. input.isDirty is true while the value is a non-empty string, whether or not it is a valid time.
revision goes up when the model holds a new settled value worth validating. Watch it to validate on input, as TimePicker does:
import { watch } from 'vue'
import { createTimePicker } from '@vuetify/v0'
const time = createTimePicker({ required: true })
watch(time.revision, () => time.input.validate())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, when 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 accepts late, as Refused updates describes, 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.
A call that does not move a field is not an edit. commit with the value a field already holds leaves a pristine value pristine.
input.reset() writes the initial value back, drops a partly entered time, and clears the validation state and isTouched. While the picker is 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. A disabled or readonly picker still validates: validate() reads the model as it is and writes nothing.
The picker reads required and rules once, at creation.
Development warnings
In development the picker logs a warning through useLogger when:
valuereceives a string that is not a 24-hourHH:mmorHH:mm:sstime.nulland''are silent.minormaxdoes not parse. The picker ignores that bound.minis later thanmax. The picker ignores the range.
Reactivity
| Property / method | Reactive | Notes |
|---|---|---|
value | 24-hour string, or null while a field is empty | |
hour | 0–23 in h23, 1–12 in h12, or null | |
minute | 0–59, or null | |
second | 0–59, or null when seconds are off or unset | |
period | 'am' or 'pm' in h12, null in h23. With an empty hour it is the remembered period | |
hourCycle | Resolved cycle | |
seconds | Whether the string includes seconds | |
isDisabled | Resolved disabled flag | |
isReadonly | Resolved readonly flag | |
display | The time the fields show, as the canonical string, or null while a field is empty | |
commit | Sets one field to the nearest multiple of its step. Null clears that field only. A period commit moves a set hour to the other half of the day, and does nothing for the period the hour is already in | |
step | Moves one field by a signed number of intervals. Wraps | |
clear | Clears every field and resets the period to 'am'. The value becomes null | |
grid | Lowest value, highest value, and step of a numeric field. Reads reactive state, so it tracks inside a getter or a template | |
revision | Goes up when the model holds a new settled value worth validating. The picker’s own normalizing counts only once the value already has a validity. A reset does not count unless error or errorMessages is set | |
input | The createInput context. Its errors, isValid, isValidating, isPristine, isDirty, isTouched, isFocused, and state are refs |
Examples
09:00
Recipes
Set the hour and the minute
Incomplete · pristine
FAQ
A partial time is not a time string. commit('hour', 9) alone leaves value null. commit('minute', 30) publishes 09:30. With seconds, the second needs a value too. commit(part, null) clears that one field and the value goes back to null.
hour reads 1 through 12, and value stays 24-hour. The picker reads commit('hour', 3) as 3 in the current period, and holds a number outside 1–12 inside that range. commit('period', 'pm') shifts a set hour by 12. 12 AM is 00 and 12 PM is 12.
They keep a complete value inside the window. A value outside it moves to the nearest time inside it that is on every field’s step, so minuteStep: 15 with min: '10:07' starts at 10:15. If no on-step time lies between the bounds, the picker clamps the value to the bound itself. An incomplete value stays null, and the bounds leave it alone. If both bounds parse and min is later than max, neither applies.
While a field is still empty the value is already null, so writing null again changes nothing and the picker sees no change. Call clear() to empty the fields.
The fields take the model’s value as given and the picker writes nothing more. The fields and display settle within two ticks of the refused write, and rendered output follows one render later. If the owner answered with a different value instead, the picker normalizes it and writes back once. See Refused updates. Read display for the time the fields show.