Skip to main content
Vuetify0 Logo
Theme
Mode
Palettes
Accessibility
Vuetify One
Sign in to Vuetify One

Access premium tools across the Vuetify ecosystem — Bin, Play, Studio, and more.

Not a subscriber? See what's included

TimePicker

Edit
Report a Bug
Issues
Source
Markdown

PreviewRenders elementIntermediateNov 18, 2026

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

09:30

Theme
Mode
Palettes
Accessibility
basic.vue
<script setup lang="ts">
  import { TimePicker } from '@vuetify/v0'
  import { shallowRef } from 'vue'

  const value = shallowRef<string | null>('09:30')
</script>

<template>
  <div class="flex flex-col items-start gap-3">
    <TimePicker.Root v-model="value" class="flex items-center gap-2">
      <TimePicker.Hour
        v-slot="{ text }"
        class="w-16 h-12 flex items-center justify-center border border-divider rounded tabular-nums"
      >
        {{ text || '—' }}
      </TimePicker.Hour>

      <span aria-hidden="true">:</span>

      <TimePicker.Minute
        v-slot="{ text }"
        class="w-16 h-12 flex items-center justify-center border border-divider rounded tabular-nums"
      >
        {{ text || '—' }}
      </TimePicker.Minute>
    </TimePicker.Root>

    <p class="text-sm text-on-surface-variant">
      {{ value ?? 'Set the hour and the minute' }}
    </p>
  </div>
</template>

Anatomy

vue
<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.

TimePicker Architecture

Use controls to zoom and pan. Click outside or press Escape to close.

TimePicker Architecture

Examples

Office hours

A 12-hour picker that stays inside a workday. The hour field shows 1 through 12, and the period field shows AM or PM. The model is still a 24-hour string, so 9 AM is 09:00 and 5 PM is 17:00.

min and max keep a complete value inside the window. The bounds live in office.ts as 09:00 and 17:00. Step the hour up from 5 PM and the next hour is 18:00, then the upper bound pulls the value back to 17:00. Switch 9 AM to PM and the stored hour shifts by 12, from 09:00 to 21:00, and the same bound pulls it back to 17:00. The hour stays inside its half of the day, so ArrowUp on 11 AM wraps to 12 AM, which is 00:00, and the lower bound pulls that up to 09:00.

Seconds stay off, so the second field is not in the tree. Focus a field and use the keys under Keyboard Navigation. On the period field, either arrow toggles AM and PM.

FileRole
office.tsOpen and close bounds
office.vue12-hour picker and the stored value
09
00
AM

Open 09:00 to 17:00. Stored value: 09:00

Theme
Mode
Palettes
Accessibility

Validation

A required picker inside a Form. The Book button calls submit from the Form’s slot, which validates every field in the form. Press it with a field still empty and the submit fails: the model is null, so required rejects it, the fields get aria-invalid, and TimePicker.Error shows the message. Set both fields and the submit passes, unless the time is 12:00, which the rule in rules turns down.

TimePicker.Description holds the help text. While it is mounted, Root and every field point at it with aria-describedby. The border color comes from data-state on Root, which reads pristine, valid, or invalid.

—
—
Pick a pickup time. The desk is closed at noon.

Not booked

Theme
Mode
Palettes
Accessibility

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.

vue
<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.

vue
<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 reset from the Root slot to put the initial value back.

vue
<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.

vue
<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.

vue
<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:

AttributeValuesComponents
data-parthour, minute, second, periodHour, Minute, Second, Period
data-stateempty, filledHour, Minute, Second. Period is always filled
data-statepristine, valid, invalidRoot. pristine until the first validation
data-dirtytrueRoot, while the model holds a value
data-focusedtrueRoot, while one of the fields has focus and the picker is not disabled
data-completetrueRoot, while the fields show a complete time
data-disabledtrueRoot, Hour, Minute, Second, Period
data-readonlytrueRoot, 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

AttributeValueNotes
rolegroupRoot
rolespinbuttonHour, Minute, Second, Period
aria-labelLabel textRoot and fields. The ariaLabel prop, or the locale string. Absent when you pass ariaLabelledby
aria-labelledbyElement idRoot and fields, from the ariaLabelledby prop
aria-describedbyElement idsRoot: the ariaDescribedby prop, then the Description while one is mounted. Fields: the Description
aria-requiredtrueFields, when Root is required
aria-invalidtrueFields, while validation has failed or error is set
aria-errormessageElement idFields, while an Error is mounted and there are messages
aria-valuenowCurrent numberAbsent while the field is empty. Period is 0 for AM and 1 for PM
aria-valueminLowest value the field can showFollows the step, and in 12-hour mode the current AM or PM half. Period is 0
aria-valuemaxHighest value the field can showFollows the step, and in 12-hour mode the current AM or PM half. Period is 1
aria-valuetextAM or PMPeriod
aria-valuetextHour and period, such as 3 PMHour in 12-hour mode, while it has a value. The 24-hour hour, the minute, and the second have none
aria-readonlytrueFields, when Root is readonly
aria-disabledtrue or falseRoot 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:

KeyAction
ArrowUpMove up one interval. Wraps past the highest value
ArrowDownMove down one interval. Wraps past the lowest value
PageUpMove the hour up about 2 hours, or the minute or second up about 15, in whole intervals and never less than one
PageDownMove the hour down about 2 hours, or the minute or second down about 15, in whole intervals and never less than one
HomeSet the lowest value the field can show
EndSet the highest value the field can show
Backspace / DeleteClear 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:

KeyAction
ArrowUp / ArrowDownToggle AM and PM
PageUp / PageDownToggle AM and PM
HomeSet AM
EndSet 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.

KeyDefaultUsed for
TimePicker.labelTimeRoot aria-label
TimePicker.hourHourHour aria-label
TimePicker.minuteMinuteMinute aria-label
TimePicker.secondSecondSecond aria-label
TimePicker.periodAM/PMPeriod aria-label
TimePicker.amAMPeriod text and aria-valuetext
TimePicker.pmPMPeriod 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.requiredRequiredMessage 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

Discord
Need help? Join our community for support and discussions ↗
Was this page helpful?

© 2016-1970 Vuetify, LLC
Services
Ctrl+/