Time input
A time field in one of three forms: typed with a mask, filled from a clock, or a list of times at a fixed interval. The value is always a 24-hour HH:mm string.
Usage
Examples
Label, hint and icon
label and hint behave as on any field. pickerIcon changes the glyph that opens the clock, iconStart puts an icon at the start of the field, and loading shows a spinner in place of the clock icon. pickerIconLabel, clearLabel, loadingText and iconStartLabel rename what each of them announces.
Type it or pick it from the clock
The glyph that opens the clock is yours to choose
An icon at the start, a spinner at the end while something loads
Sizes
size sets the field height to 32, 40 or 48 pixels, and compact takes 4px off it. The clock keeps its own measurements.
Modes
mode chooses the form of the field: input masks it so only digits are typed, the clock then being opt-in through showPicker; picker makes the clock the only way in, so it is forced on there; list drops the clock for a searchable list of times.
No icon, no panel: the mask is the whole control
showPicker adds the icon and the panel it opens
Nothing can be typed, so the clock is the only way in
Every half hour, found by typing rather than by scrolling
Steps
minuteStep is what the face offers, what the arrow keys move by and what the list is cut at. It leaves the mask alone, and is worth setting on a list before anything else: the default of one minute is 1440 rows.
The face offers four minutes an hour, and the arrow keys move by the same step
The step is what the rows are cut at: 48 of them here rather than 1440
The mask still takes any time; the step drives the clock and the arrow keys
What may be chosen
min, max, allowedHours and allowedMinutes restrict what may be chosen. The list and the clock leave out what cannot be chosen; the typed field commits the entry and turns invalid through the control's own validity instead.
Type 08:00 and leave the field: the value stands and the field turns invalid
The rows outside the bounds are not offered at all
The face prints only the hours it can take
Clearable
clearable adds a cross that empties the value, to the left of the clock icon rather than in its place. The list form takes its own cross from the combobox it is built on, wording included.
The cross sits to the left of the clock icon, never in its place
Emptying the field is then the reader's own business
Here the cross is the combobox's own, chevron included
States
invalid is for a rule the browser cannot check by itself. disabled greys the field out and prevents the panel from opening. readonly shows the value frozen: nothing can be typed, no clock is rendered and the AM/PM button goes with it, while the field keeps its contrast and takes the focus.
For a rule the browser cannot check by itself
Greyed through the colour tokens, and the panel can no longer be opened
No typing, no clock, no clear cross
Twelve-hour clock
The value is a 24-hour string whatever is on screen. Where the half of the day is chosen depends on the form: a button inside a typed field, the clock's own pair beside its numerals, and nothing in a list, every row spelling out its own.
The mask says nothing about the half of the day, so a button in the field does
Here the pair belongs to the clock, beside its two large numerals
Every row spells its own half of the day, so neither control is needed
Localization
locale decides the clock, the mask and how a time is written out, and takes precedence over the global locale. format sits above both, for a field that has to be read one way whatever the language.
format overrides what the tag would have chosen
Placement
placement names the preferred opening direction of the panel, above or below the field.
API
Props
| Prop | Type | Default |
|---|---|---|
format | TimePickerFormat'12h' | '24h' | none |
| Whether times are shown on a 12- or a 24-hour clock. Left out, the reader's language decides, which is almost always what one wants. | ||
mode | TimeInputMode'picker' | 'input' | 'list' | 'input' |
Which form the field takes: one that can be typed into, a picker one where the clock is the only way in, so the clock is forced on there, or a list of times at a fixed interval, where a clock would make no sense. It is a different question from readonly, which freezes the field by every route at once. | ||
showPicker | boolean | false |
Offers the picker beside a field one can type into: an icon at the end of the field, and a panel that opens on focus. The clock follows what is typed, and with no value it opens empty. It means nothing in picker mode, where the clock is forced on, nor in list mode, where the list is the panel. | ||
minuteStep | number | 1 |
| The interval between two times that can be chosen. It applies to the picker, to the arrow keys and to the rows of the list. | ||
min | string | none |
| The earliest time that can be chosen, inclusive, as a canonical 24-hour string. The picker and the list both leave out what it rules out, and a time typed past it makes the field invalid. | ||
max | string | none |
| The latest time that can be chosen, inclusive, written like min. | ||
allowedHours | TimePickerAllowed | none |
| Which hours can be chosen: the list of them, or a rule answering for one. The hour a rule is handed is always the 24-hour one, whichever clock is on display. | ||
allowedMinutes | TimePickerAllowed | none |
| Which minutes can be chosen: the list of them, or a rule answering for one. | ||
locale | string | none |
| A BCP 47 locale, which decides the clock and how a time is written out. It takes precedence over the design system's global locale and falls back to it. | ||
label | string | none |
| The label above the field. | ||
hint | string | none |
| A line of help under the field. | ||
placeholder | string | none |
| What the field says while empty. | ||
size | TimeInputSize'sm' | 'md' | 'lg' | 'md' |
| The height of the field: 32, 40 or 48 pixels. | ||
compact | boolean | false |
| Takes 4px off the height. | ||
disabled | boolean | false |
| Makes the field unusable, greyed out through the colour tokens. | ||
readonly | boolean | false |
Shows the time without letting it be changed: nothing can be typed, there is no clock and no clear cross, and the attributes announcing a panel go with it. The field keeps the focus and can be copied from, which is what separates it from disabled. | ||
invalid | boolean | false |
| Marks the field as invalid, for a rule of your own. | ||
iconStart | IconSource | none |
An icon inside the field, at the start. Decorative until a @click:icon-start listener turns it into a button. | ||
iconStartLabel | string | none |
| What the start icon does, in words, once it is clickable. | ||
pickerIconLabel | string | none |
| What the end icon does, in words. It names the button that opens the clock, and falls back to the design system dictionary. | ||
loading | boolean | false |
| Shows a spinner in place of the clock icon. It says that something is being loaded and changes nothing else: the field can still be typed into and the panel still opens. | ||
loadingText | string | none |
| What screen readers announce while the spinner turns. It falls back to the design system dictionary. | ||
clearable | boolean | false |
| Offers a cross that empties the value, shown before the end icon. | ||
clearLabel | string | none |
| What that cross does, in words. It falls back to the design system dictionary. | ||
pickerIcon | IconSource | schedule |
| The icon that opens the clock, at the end of the field. It has no effect on the list form, whose chevron follows the combobox convention. The clear cross appears to its left rather than in its place. | ||
placement | TimeInputPlacement'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end' | 'bottom-start' |
| Where the panel opens relative to the field. | ||
v-model | string | null | null |
| The time, always as a 24-hour string whatever clock is displayed, so you never have to know which one the reader's language uses. | ||
Events
| Event | Type |
|---|---|
click:icon-start | [event: MouseEvent] |
The start icon was clicked. Attaching this listener is what turns that icon into a real button, which then needs iconStartLabel. | |
clear | [] |
| The clear cross emptied the field. The value has already been reset. | |
Slots
| Slot | Type |
|---|---|
start | {} |
Content at the start of the field, rendered after iconStart rather than in its place. | |
value-end | {} |
Controls of your own inside the field, placed before the ones the field owns: the clear cross and the icon that opens the panel. Those two are the component own affordance, which is why there is no end slot here. | |
footer | TimeInputFooterSlotProps |
The strip at the foot of the clock, which replaces the Cancel and OK buttons rather than joining them. It receives both actions, and they are what make it usable: the clock writes a draft that only confirm commits, so a footer of your own without it would leave the value unchangeable through the panel. It also receives cancel, and close, the same function under the name VDateInput's footer hands out. It is not rendered in list mode, which has no panel of its own. | |
Types
The types the tables above name, written as the library declares them. The ones carrying export can be imported from vectis-ui to type your own code; the others are the shape of what a slot hands out.
export interface BuiltinIcon {
name: string
paths: readonly [string] | readonly [string, string]
}export type IconRender =
| { path: string; viewBox?: string }
| { component: Component; props?: Record<string, unknown> }
| { src: string }
| { text: string; class?: string }
| { class: string }export type IconSource = string | BuiltinIcon | IconRender
export type TimePickerAllowed = number[] | ((value: number) => boolean)