TimePicker
Edit a time as hour, minute, and optional second fields. The control stores a 24-hour string, and 12-hour mode adds an AM/PM field.
Usage
Each field is a spinbutton. The arrow, Page, Home, and End keys move it. The model stays null until both the hour and the minute have a value.
09:30
Anatomy
<script setup lang="ts">
import { TimePicker } from '@vuetify/v0'
</script>
<template>
<TimePicker.Root>
<TimePicker.Hour />
<TimePicker.Minute />
<TimePicker.Second />
<TimePicker.Period />
<TimePicker.Description />
<TimePicker.Error />
<TimePicker.HiddenInput />
</TimePicker.Root>
</template>Architecture
Root owns the time value. Hour, Minute, Second, and Period each read and edit one field of it. Second renders only when seconds is on. Period renders only when hour-cycle is h12. Description and Error hold the help text and the validation messages, and Root links the fields to them. HiddenInput carries the displayed time into a form, and Root renders it when you set name.
Examples
Open 09:00 to 17:00. Stored value: 09:00
Validation
Root takes required, rules, error, and errorMessages, and registers with a parent Form, so a form submit validates the picker. The picker validates the model: a 24-hour string, or null while a field is empty. Each rule receives it and returns true, or a message.
validateOn sets when the picker validates on its own. It defaults to 'blur', and takes the same values as Input: 'blur', 'input', or 'submit', optionally with lazy or eager. The picker counts as blurred when focus leaves the group. Focus moving from one field to another is not a blur, so a required picker does not report an error while you tab from the hour to the minute. 'input' validates when a key changes the time and when a value arrives from outside, as NumberField does. The picker validates a value from outside once, in the form it settles on after applying the step and the bounds. The picker normalizing on its own, at mount, when disabled or readonly turns off, or when a step or a bound changes, is input only once the picker has a validity: the picker then validates the new value too, so the state on show does not go stale. A validity comes from a validation, or from error or errorMessages, which set one without a validation having run. A picker that has no validity yet stays that way, and the slot’s reset is not input unless error or errorMessages is set. Both hold for a parent that answers an update at once. When a parent accepts late, the picker reads its answer as a value from outside, which is input: see What if the parent refuses an update?. A normalization that lands while the first async validation is still pending is not input, so that result describes the earlier value. A disabled picker does not validate from focus, and focus inside it does not set data-focused until disabled turns off.
Root reads required and rules once, at setup. Changing them later has no effect.
error forces the invalid state, and errorMessages come before the messages the rules produce.
The Root slot exposes errors, isValid, isPristine, isFocused, validate, and reset. A value the picker moved onto the step or inside the bounds is still pristine. reset puts the initial value back, drops a partly entered time, and clears the validation state. While the picker is disabled or readonly it does not emit: it clears the validation state and leaves the time alone. isPristine reads true after a reset even when the parent refuses the value.
Recipes
Quarter hours
minute-step keeps the minute on the multiples of the step. With a step of 15, ArrowUp moves 00, 15, 30, 45 and wraps to 00, and ArrowDown runs the other way. A value that arrives off the step moves to the nearest multiple without wrapping, and the picker writes it back, so 09:50 becomes 09:45. hour-step and second-step work the same way.
<template>
<TimePicker.Root v-model="value" :minute-step="15">
<TimePicker.Hour v-slot="{ text }">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }">{{ text }}</TimePicker.Minute>
</TimePicker.Root>
</template>Bounds and steps together
A complete value outside min and max moves to the nearest time inside them that is also on every field’s step. With minute-step="15", min="10:07" starts the range at 10:15, and max="17:10" ends it at 17:00. Only when no such time lies between the bounds does the picker set the step aside and clamp the value to the bound itself.
<template>
<TimePicker.Root v-model="value" max="17:10" min="10:07" :minute-step="15">
<TimePicker.Hour v-slot="{ text }">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }">{{ text }}</TimePicker.Minute>
</TimePicker.Root>
</template>Submit with a form
Set name and Root renders TimePicker.HiddenInput for you. The input submits the time the fields show as a 24-hour string, and an empty string while a field is empty. Set form to the id of a form when Root sits outside it.
Do not also place TimePicker.HiddenInput yourself. Inside a Root that has name it submits the value a second time, and inside a Root without name it has no name and submits nothing.
A readonly picker still submits. It sends the time the fields show, which is an empty string when the model holds a string that is not a time.
The browser leaves a disabled picker out of the submission.
A native form reset does not restore the picker. A Form reset clears its validation state and leaves the time alone. Call
resetfrom the Root slot to put the initial value back.
<template>
<form>
<TimePicker.Root v-model="value" name="alarm">
<TimePicker.Hour v-slot="{ text }">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }">{{ text }}</TimePicker.Minute>
</TimePicker.Root>
</form>
</template>Two pickers on one page
By default the locale catalog names every Root “Time”, and every field “Hour”, “Minute”, “Second”, or “AM/PM”. Give a start and an end picker their own names with ariaLabel, or point ariaLabelledby at a visible label. Both props exist on Root and on each field, and ariaLabelledby replaces ariaLabel.
Each field builds its id from the Root id and the field’s kind. Two fields of the same kind inside one Root, such as a mobile and a desktop Hour, would share that id, so pass id to each.
<template>
<span id="start-label">Start</span>
<TimePicker.Root v-model="start" aria-labelledby="start-label">
<TimePicker.Hour v-slot="{ text }" aria-label="Start hour">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }" aria-label="Start minute">{{ text }}</TimePicker.Minute>
</TimePicker.Root>
<TimePicker.Root v-model="end" aria-label="End time">
<TimePicker.Hour v-slot="{ text }" aria-label="End hour">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }" aria-label="End minute">{{ text }}</TimePicker.Minute>
</TimePicker.Root>
</template>Clear the value
The Root slot exposes clear, which empties every field and sets the model to null. It does nothing while the picker is disabled or readonly.
<template>
<TimePicker.Root v-slot="{ clear }" v-model="value">
<TimePicker.Hour v-slot="{ text }">{{ text }}</TimePicker.Hour>
<TimePicker.Minute v-slot="{ text }">{{ text }}</TimePicker.Minute>
<Button.Root @click="clear">Clear</Button.Root>
</TimePicker.Root>
</template>Data Attributes
Style field and interaction states without slot props:
| Attribute | Values | Components |
|---|---|---|
data-part | hour, minute, second, period | Hour, Minute, Second, Period |
data-state | empty, filled | Hour, Minute, Second. Period is always filled |
data-state | pristine, valid, invalid | Root. pristine until the first validation |
data-dirty | true | Root, while the model holds a value |
data-focused | true | Root, while one of the fields has focus and the picker is not disabled |
data-complete | true | Root, while the fields show a complete time |
data-disabled | true | Root, Hour, Minute, Second, Period |
data-readonly | true | Root, Hour, Minute, Second, Period |
Accessibility
Root renders role="group". Each field renders role="spinbutton" per the WAI-ARIA Spinbutton pattern↗︎. Names come from the locale catalog unless you pass ariaLabel or ariaLabelledby.
ARIA Attributes
| Attribute | Value | Notes |
|---|---|---|
role | group | Root |
role | spinbutton | Hour, Minute, Second, Period |
aria-label | Label text | Root and fields. The ariaLabel prop, or the locale string. Absent when you pass ariaLabelledby |
aria-labelledby | Element id | Root and fields, from the ariaLabelledby prop |
aria-describedby | Element ids | Root: the ariaDescribedby prop, then the Description while one is mounted. Fields: the Description |
aria-required | true | Fields, when Root is required |
aria-invalid | true | Fields, while validation has failed or error is set |
aria-errormessage | Element id | Fields, while an Error is mounted and there are messages |
aria-valuenow | Current number | Absent while the field is empty. Period is 0 for AM and 1 for PM |
aria-valuemin | Lowest value the field can show | Follows the step, and in 12-hour mode the current AM or PM half. Period is 0 |
aria-valuemax | Highest value the field can show | Follows the step, and in 12-hour mode the current AM or PM half. Period is 1 |
aria-valuetext | AM or PM | Period |
aria-valuetext | Hour and period, such as 3 PM | Hour in 12-hour mode, while it has a value. The 24-hour hour, the minute, and the second have none |
aria-readonly | true | Fields, when Root is readonly |
aria-disabled | true or false | Root and fields. Absent on a native button host, which uses disabled |
With the default steps the hour runs 0–23, or 1–12 in 12-hour mode, and the minute and second run 0–59. A step narrows the range to its multiples: minute-step="15" gives a minute range of 0–45. While Root is disabled or readonly the fields report their whole range instead, because the fields show the value as given and it may sit off the step.
The reported range always includes the value the field shows. When that value is off the step, the range widens to take it in.
The min and max props do not narrow aria-valuemin and aria-valuemax. They apply to the whole time, not to one field. At a bound, a key that would take the time out of the range leaves it unchanged.
Each field is a tab stop. Disabled fields use tabindex="-1". Readonly fields stay focusable.
Keep the fields on a non-button element. as="button" is not a suitable host: role="spinbutton" is not an allowed role on <button> in ARIA in HTML, and axe reports it as aria-allowed-role.
Keyboard Navigation
Hour, Minute, and Second:
| Key | Action |
|---|---|
ArrowUp | Move up one interval. Wraps past the highest value |
ArrowDown | Move down one interval. Wraps past the lowest value |
PageUp | Move the hour up about 2 hours, or the minute or second up about 15, in whole intervals and never less than one |
PageDown | Move the hour down about 2 hours, or the minute or second down about 15, in whole intervals and never less than one |
Home | Set the lowest value the field can show |
End | Set the highest value the field can show |
Backspace / Delete | Clear the field. The model becomes null |
An empty field lands on its first value on any arrow or Page key. In 12-hour mode the hour field counts in display numbers, so Home sets 1 and End sets 12 with the default step.
Period:
| Key | Action |
|---|---|
ArrowUp / ArrowDown | Toggle AM and PM |
PageUp / PageDown | Toggle AM and PM |
Home | Set AM |
End | Set PM |
Backspace and Delete do nothing on Period. The fields do not take typed digits.
The fields ignore every key while Root is disabled or readonly. An ignored key keeps its browser default, so the arrow keys, Page, Home, and End scroll the page from a focused readonly field.
Locale Keys
The names and spoken text come from useLocale. Without the locale plugin, or without a translation for a key, the picker uses the English default.
| Key | Default | Used for |
|---|---|---|
TimePicker.label | Time | Root aria-label |
TimePicker.hour | Hour | Hour aria-label |
TimePicker.minute | Minute | Minute aria-label |
TimePicker.second | Second | Second aria-label |
TimePicker.period | AM/PM | Period aria-label |
TimePicker.am | AM | Period text and aria-valuetext |
TimePicker.pm | PM | Period text and aria-valuetext |
TimePicker.hourText | {hour} {period} | aria-valuetext of the hour in 12-hour mode. A locale can reorder the two parts |
Input.required | Required | Message of the required rule |
An ariaLabel or ariaLabelledby prop takes priority over the label keys.
The locale’s n() formats the digits a field shows, and the field pads them to two digits with the locale’s zero. The hour in a 12-hour aria-valuetext goes through n() too, without padding. Under a locale with its own numerals, such as ar-EG, the fields show those. The model, the Root slot’s value, and the submitted value stay in Latin digits.
FAQ
The model stays null until both the hour and the minute have a value. With seconds, a time you enter field by field also needs the second. A value that arrives as HH:mm while seconds is on reads as second 00, so 09:30 becomes 09:30:00, and turning seconds on for a picker whose hour and minute have values keeps the time with second 00. Clearing any field sets the model back to null.
The stored value is always 24-hour. The hour field shows 1 through 12, and the period field shifts that hour by 12. 12 AM is 00 and 12 PM is 12.
They keep a complete value inside the window. An incomplete value stays null. A value outside the window moves to the nearest time inside it that is on every field’s step, so with minute-step="15" and min="10:07" the earliest value is 10:15. If no such time lies between the bounds, the picker clamps the value to the bound itself. Bounds use the same 24-hour form as the model, and their seconds count only when seconds is on.
Both ignore every key and clear, and the picker never emits while either is on, not even from the slot’s reset. An ignored key keeps its browser default, so the arrow keys, Page, Home, and End scroll the page. The fields show the value as given, and the picker does not apply the step or min and max. When the picker is editable again it applies them and emits the result. disabled also takes the fields out of the tab order and keeps the hidden input out of form submission. readonly keeps the fields focusable, sets aria-readonly, and still submits the displayed time.
The fields follow the model. When the parent does not accept an emitted value, the fields take the model’s value as given, and the picker applies neither the step nor the bounds and emits nothing more. The parent sees one update:modelValue. The fields return to the model’s time once the picker has checked the parent’s answer, on the render that follows, so wait for the DOM to update rather than for a fixed number of ticks.
When the parent replaces the emitted value with a different one, the picker treats the replacement as an incoming value: it normalizes it and emits the result once. If the parent changes that too, the picker takes the parent’s value as given and stops. One edit emits at most twice.
The same holds on mount. A picker that normalizes its initial value emits once, and a parent that replaces that value with a different one gets one more emit a tick later. A parent that only refuses gets one.
A key you press while the fields show a value they took as given edits what they show. The field moves by the usual rules, then the picker normalizes the whole time and emits it once: with minute-step="15" and fields showing 04:50, ArrowDown gives 04:45.
Two things follow:
Accept or refuse synchronously. A parent 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 time in between, and each rapid key press starts from it. Bind the picker to a local ref and debounce or validate downstream of that ref.
Give the picker the same step the parent rounds to. A parent that rounds to 30 minutes over a picker with the default
minute-stepgets09:01on ArrowUp and maps it straight back, so the field returns to09:00every time. Withminute-step="30"the picker emits09:30.