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

createTimePicker API

Segmented time value with hour, minute, and second fields, 12/24-hour modes, meridiem handling, step snapping, and min/max bounds.

Explore these related pages for additional context and usage patterns.

PageCategory
createTimePickerForms
Time PickerForms
createNumericForms

Functions

createTimePicker

(_options?: TimePickerOptions) => TimePickerContext

Creates a segmented time value.

Options

id

ID | undefined

Unique identifier (auto-generated if omitted).

label

string | undefined

Display label.

name

string | undefined

Form field name.

form

string | undefined

Associate with form by ID.

formNamespace

string | undefined

Form injection key. Must match the parent Form's namespace.

Default: 'v0:form'

required

boolean | undefined

Whether required. When true, a presence rule is registered so Form submit fails on empty values even with novalidate.

disabled

MaybeRefOrGetter<boolean> | undefined

Disabled state.

readonly

MaybeRefOrGetter<boolean> | undefined

Readonly state.

rules

(string | FormValidationRule | StandardSchemaV1)[] | undefined

Validation rules.

error

MaybeRefOrGetter<boolean> | undefined

Manual error state override — forces invalid.

errorMessages

MaybeRefOrGetter<MaybeArray<string> | undefined>

Manual error messages — merged with rule-based errors.

value

Ref<string | null, string | null> | undefined

Canonical 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> | undefined

Include 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

secondStep

MaybeRefOrGetter<number | undefined>

Second interval. Same rules as minuteStep.

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.

minute

Readonly<Ref<number | null, number | null>>

Minute field, 0–59, or 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'.

hourCycle

Readonly<Ref<TimeHourCycle, TimeHourCycle>>

Resolved hour cycle.

seconds

Readonly<Ref<boolean, boolean>>

Whether the canonical value includes seconds.

isDisabled

Readonly<Ref<boolean, boolean>>

Resolved disabled flag.

isReadonly

Readonly<Ref<boolean, boolean>>

Resolved readonly flag.

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) => void

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

clear

() => void

Clear every field and forget the meridiem. The value becomes null.

grid

(part: TimeUnit) => TimeGrid

Lowest and highest grid values of a numeric field, plus its resolved step. An h12 hour reports display hours for the current meridiem.

Was this page helpful?

© 2016-1970 Vuetify, LLC
Services
Ctrl+/