# createTimePicker API

> Auto-generated API reference for `createTimePicker` from @vuetify/v0 (Vuetify0).
> Source of truth: https://0.vuetifyjs.com/api/create-time-picker

## Related

- https://0.vuetifyjs.com/composables/forms/create-time-picker
- https://0.vuetifyjs.com/components/forms/time-picker
- https://0.vuetifyjs.com/composables/forms/create-numeric

## Functions

### createTimePicker

Creates a segmented time value.

```ts
(_options?: TimePickerOptions) => TimePickerContext
```

## Options

| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| `id` | `ID \| undefined` | — | no | Unique identifier (auto-generated if omitted). |
| `label` | `string \| undefined` | — | no | Display label. |
| `name` | `string \| undefined` | — | no | Form field name. |
| `form` | `string \| undefined` | — | no | Associate with form by ID. |
| `formNamespace` | `string \| undefined` | `'v0:form'` | no | Form injection key. Must match the parent Form's `namespace`. |
| `required` | `boolean \| undefined` | — | no | Whether required. When true, a presence rule is registered so Form submit fails on empty values even with `novalidate`. |
| `disabled` | `MaybeRefOrGetter<boolean> \| undefined` | — | no | Disabled state. |
| `readonly` | `MaybeRefOrGetter<boolean> \| undefined` | — | no | Readonly state. |
| `rules` | `(string \| FormValidationRule \| StandardSchemaV1)[] \| undefined` | — | no | Validation rules. |
| `error` | `MaybeRefOrGetter<boolean> \| undefined` | — | no | Manual error state override — forces invalid. |
| `errorMessages` | `MaybeRefOrGetter<MaybeArray<string> \| undefined>` | — | no | Manual error messages — merged with rule-based errors. |
| `value` | `Ref<string \| null, string \| null> \| undefined` | `shallowRef(null)` | no | 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. |
| `hourCycle` | `MaybeRefOrGetter<TimeHourCycle \| undefined>` | `'h23'` | no | `h12` shows 1–12 and a meridiem. `h23` shows 0–23. The picker reads any other value as `h23`. |
| `seconds` | `MaybeRefOrGetter<boolean> \| undefined` | `false` | no | 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. |
| `hourStep` | `MaybeRefOrGetter<number \| undefined>` | `1` | no | 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. |
| `minuteStep` | `MaybeRefOrGetter<number \| undefined>` | `1` | no | 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. |
| `secondStep` | `MaybeRefOrGetter<number \| undefined>` | `1` | no | Second interval. Same rules as `minuteStep`. |
| `min` | `MaybeRefOrGetter<string \| null \| undefined>` | — | no | 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>` | — | no | 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. |

## Methods

| Name | Type | Description |
|---|---|---|
| `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. |

## Properties

| Name | Type | Description |
|---|---|---|
| `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. |
