<c-time-picker>
A time field that takes a typed time, or opens hour and minute columns for picking one, or a start and end time under `range`.
Usage
Value
The value is a time of day as an ISO HH:mm string on a 24-hour clock —
'14:05' — or null when the field is empty. It carries no seconds, no date
and no timezone, and whatever the displayed format it keeps this one shape:
a field showing 14.05 or 2:05 PM holds '14:05'. Bind it with v-model,
or listen for change:
<c-time-picker v-model="time" label="Start time" />
Under range the value becomes { start, end }. Either end may be null
while only one is set — { start: '09:00', end: null } — and a range with
neither end is null.
Typing
The field is typeable first: clicking into it or focusing it never opens the
columns. Text is read when the user presses Enter or leaves the input, never
per keystroke. The format prop sets how times are shown and read — a pattern
of the tokens H or HH (a 24-hour hour), h or hh (a 12-hour hour, which
needs the period a) and mm, with any separators. The default is HH.mm;
HH:mm and h:mm a are common alternatives. The format is an app default, so
an app can set it once with applyDefaults({ 'c-time-picker': { format: 'HH:mm' } }).
Typing follows the format as it goes: the separator appears on its own (930
shows 9.30), an hour closes early when its first digit can start no
two-digit hour, any of ., : or a space typed in place of the separator
shows as the format's own, and in a 12-hour format a typed a or p fills in
the whole AM or PM text. Reading is lenient:
| Typed | Reads as |
|---|---|
9 |
09:00 — a bare hour is on the hour |
930 |
09:30 — three or four digits split |
9.3 |
09:03 — one minute digit is that minute |
2 pm |
14:00 — a period makes the hour 12-hour |
14.00 |
14:00, also in a 12-hour field (2:00 PM) |
In a 12-hour field an hour typed without a period reads as AM.
Text that names no time that can be picked — 25.00, a time outside min
and max — is bad input: the text stays as the user typed it, the value
becomes null, and the host exposes the bad-input custom state and a
read-only badInput property. The component never shows an error of its own;
deciding whether bad input is an error, and saying so, is the consumer's
validation:
<c-time-picker
v-model="time"
:error-message="error"
:invalid="!!error"
label="Start time"
@change:text="error = $event.target.badInput ? 'Enter a time as hh.mm' : ''"
/>
Every commit of typed text fires change:text with the text as typed
({ start, end } under range), whether or not it changed the value.
The columns
The clock button at the field's trailing edge, or Alt+ArrowDown in the input,
opens the columns: hours and minutes side by side, and an AM/PM column in a
12-hour format. The panel is a dialog: focus moves onto the hour column —
the value's hour, or the current hour when the field is empty — and Tab
cycles through the columns and the Now button (show-now) until the panel
closes.
Every pick commits at once and the panel stays open, so the hour can be fixed
after the minutes are picked (on a narrow viewport picks wait for a Done
button instead; see Narrow viewports). The selected row rests at the top of its column:
it opens there and returns there after each pick, and so does a minute a pick
fills in. Scrolling a column only looks; it never picks. Picking into an empty field fills in the rest:
minute 00, and the hour the hour column rests on. Moving in a column is
picking — each arrow key press commits, so a change handler doing network
work should debounce.
| Key | In a column |
|---|---|
| ArrowUp / ArrowDown | Previous / next row |
| Home / End | First / last row |
| PageUp / PageDown | Five rows up / down |
| Space | Pick the focused row |
| Enter | Pick the focused row and close |
| Escape | Close; what was picked stays |
| Tab | Next column (the end switch under range) |
Focus returns to the input when the panel closes.
Minute step
minute-step spaces the minute column's rows: 15 lists 00, 15, 30
and 45. It only shapes the column — a typed 14.07 commits as 14:07 and
shows as an extra row between 00 and 15. Require a step with your own
validation if it matters.
Min and max
min and max are ISO HH:mm times. Rows outside them are disabled — an
hour only when none of its minutes fit — and a typed time outside them is bad
input. A pick never leaves them: picking hour 9 at 10:15 with min="09:30"
commits 09:30. A min later than max is not a range across midnight; it
is ignored with a console warning.
Ranges
With range the field holds two inputs, the start and the end, in one field
box, and the panel shows a Start | End switch above the columns. It opens on
the end last typed in; each end commits on its own as it is picked.
An end earlier than the start is an overnight range — 22:00 to 06:00
spans midnight — and is kept as it is, never swapped or flagged. Where a range
must stay within one day, check it in your validation; ISO times compare
correctly as strings:
const sameDay =
!value || !value.start || !value.end || value.start <= value.end;
Now
show-now adds a Now button under the columns. Pressing it commits the
current time and closes the panel, unlike a pick in the columns, which leaves
it open. The time is the exact minute whatever minute-step: at 14:07 with a
step of 15 it commits 14:07. Under range it sets the end the Start | End
switch shows.
<c-time-picker v-model="arrival" label="Arrival" show-now />
The button is disabled, never hidden, while the current time is outside
min and max. Turn it on app-wide with
applyDefaults({ 'c-time-picker': { showNow: true } }).
Texts
The AM and PM texts come from texts when given, then from the browser's
Intl data for the page's lang, then from the English built-ins — so a page
with <html lang="fi"> shows ap. and ip. without any configuration. The
button, column and range labels are English unless texts replaces them. Set
them app-wide with applyDefaults({ 'c-time-picker': { texts } }).
Narrow viewports
On a viewport narrower than 760px the columns open as a fullscreen panel:
a heading row with the field's label and a close button above the columns.
There the selected row rests in the middle of its column instead of the top,
in every column, so the selections line up even when a column fits.
The fullscreen panel ends in a Done button, and there picks wait in the
panel instead of committing: nothing is emitted until Done commits the time
— under range both ends at once — and closes the panel. The close button
and Escape close the panel without a change, discarding what was picked, and
so does the window growing past 760px while it is open. The Now button moves
the columns to the current time the same way, and Enter picks the focused
row and presses Done at once. Pressing Done before picking anything closes
the panel and changes nothing. The field stays typeable at every width.
Related
c-date-picker is the same field for calendar dates. c-text-field type="time" remains the browser's own time input — no columns, the browser's
format, and no ranges.
Examples
<template>
<div>
<c-time-picker
v-model="time"
hint="Type a time or open the clock"
label="Start time"
clearable
/>
<p>Value: {{ time ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const time = ref<null | string>(null);
</script>
<template>
<div>
<c-time-picker
v-model="time"
hint="Between 8.00 and 16.00"
label="Pickup time"
max="16:00"
min="08:00"
/>
<p>Value: {{ time ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const time = ref<null | string>(null);
</script>
<template>
<div>
<c-time-picker
v-model="time"
:minute-step="15"
hint="Slots every 15 minutes; any typed time is kept"
label="Appointment"
/>
<p>Value: {{ time ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const time = ref<null | string>(null);
</script>
<template>
<div>
<c-time-picker
v-model="time"
:minute-step="15"
hint="Now under the columns commits the current minute"
label="Arrival"
show-now
/>
<p>Value: {{ time ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const time = ref<null | string>('08:00');
</script>
<template>
<div>
<c-time-picker
v-model="maintenance"
hint="An end before the start spans midnight"
label="Maintenance maintenance"
clearable
range
/>
<p>
Value:
{{ maintenance ? `${maintenance.start} – ${maintenance.end}` : 'null' }}
</p>
</div>
</template>
<script setup lang="ts">
import type { CTimePickerRange } from '@cscfi/csc-ui';
import { ref } from 'vue';
const maintenance = ref<CTimePickerRange | null>(null);
</script>
<template>
<div>
<c-time-picker
v-model="shift"
:texts
format="H.mm"
hint="Kirjoita ajat tai valitse listoista"
label="Työvuoro"
range
/>
<p>Value: {{ shift ? `${shift.start} – ${shift.end}` : 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import type { CTimePickerRange, CTimePickerTexts } from '@cscfi/csc-ui';
import { ref } from 'vue';
// Every text, so none falls back to Intl for the page's lang or to English;
// AM/PM shows in a 12-hour format, Now under show-now.
const texts: CTimePickerTexts = {
am: 'ap.',
chooseTime: 'Valitse aika',
clearSelection: 'Tyhjennä',
closePanel: 'Sulje',
done: 'Valmis',
end: 'Loppuaika',
hours: 'Tunnit',
minutes: 'Minuutit',
now: 'Nyt',
openClock: 'Avaa kellonajan valinta',
period: 'ap./ip.',
pm: 'ip.',
start: 'Alkuaika',
};
const shift = ref<CTimePickerRange | null>(null);
</script>
<template>
<div>
<c-time-picker v-model="time" format="h:mm a" label="Meeting time" />
<p>Value: {{ time ?? 'null' }}</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const time = ref<null | string>('14:30');
</script>
API reference
<c-time-picker>
A time field that takes a typed time, or opens hour and minute columns for picking one, or a start and end time under `range`.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
clearable | clearable | boolean | false | Make the value clearable |
disabled | disabled | boolean | false | Disable the field |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the field is invalid |
format | format | string | 'HH.mm' app default | How times are shown and read from typing: a pattern of the tokens `H`, `HH` (24-hour), `h`, `hh` (12-hour, with the period `a`) and `mm` with any separators, e.g. `HH:mm` or `h:mm a` |
hideMessage | hide-message | boolean | false app default | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the field |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
label | label | string | '' | Element label |
labelOnTop | label-on-top | boolean | false app default | Label on top of the field |
max | max | string | '' | The latest time that can be picked or typed, as an ISO `HH:mm` time |
min | min | string | '' | The earliest time that can be picked or typed, as an ISO `HH:mm` time; a `min` after `max` is invalid and both are ignored |
minuteStep | minute-step | number | 1 | Minutes between the minute column's rows; typed times need not fall on the step |
name | name | string | '' | The name the time submits under in a native `<form>`, as its ISO text; a `range` as one ISO 8601 interval, `start/end` |
placeholder | placeholder | string | '' | Placeholder of the input; the `format` pattern when empty |
range | range | boolean | false | Pick a range: the value becomes `{ start, end }` and the field holds two inputs |
required | required | boolean | false | Set the field as required |
shadow | shadow | boolean | false app default | Shadow variant |
showNow | show-now | boolean | false app default | Show a Now button under the columns that commits the current time |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box |
texts | — | | {} app default | UI text overrides (i18n), merged over the AM/PM texts `Intl` gives for the page's `lang` and the English defaults. Objects have no attribute form — bind as a DOM property |
value | value | | null | The time as an ISO `HH:mm` string on a 24-hour clock, or `{ start, end }` under `range`; `null` when empty |
hideDetails deprecated | hide-details | boolean | false app default | Deprecated. Use `hide-message`. Hide the hint and error messages |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Events
| Event | Detail | Description |
|---|---|---|
change | CTimePickerValue | Fired when the value changes — a row is picked or moved to in a column, typed text is committed, or the field is cleared — carrying the new value: an ISO `HH:mm` time, `{ start, end }` under `range`, or `null`. |
change:text | CTimePickerText | Fired on every commit of typed text (Enter or leaving the input) with the text as typed — `{ start, end }` under `range`. Read `badInput` to tell whether it named a time that can be picked. |
input | void | Native bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail. |
update:value | CTimePickerValue | Fired alongside `change` with the same detail — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
badInput | : boolean (read-only) | Whether the committed text names no time that can be picked — the value is then `null` (CONTEXT.md "Bad input"). |
focus | (options?: FocusOptions): void | Focus its input (the start input under `range`), as `focus()` does on a native control: the element renders no box of its own to take it. |
CSS parts
Style from outside with c-time-picker::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
input | The text input; under `range` both the start and the end input |
separator | The dash between the start and end inputs under `range` |
panel | The top-layer popover container anchored below the field |
card | The dialog surface inside the panel holding the columns |
heading-row | The top row of the fullscreen panel (narrow viewports): the field label as heading and the close button |
heading | The field label naming the fullscreen panel |
close | The close button of the fullscreen panel |
end-switch | The Start | End switch above the columns under `range` |
end | One end's button in the end switch |
columns | The row of time columns |
column | One time column: hours, minutes or AM/PM |
option | One row of a time column |
actions | The row under the columns holding the Now button (`show-now`) and, in the fullscreen panel, the Done button |
now | The Now button: commits the current time |
done | The Done button of the fullscreen panel (narrow viewports): commits what the panel holds and closes |
message | The hint / error message area below the field (always reserved unless `hide-message`) |
Custom states
Select on the host's live state with c-time-picker:state(name) — combine with ::part() for per-state styling, e.g. c-time-picker:state(checked)::part(indicator) targets the indicator only while checked.
| State | Description |
|---|---|
bad-input | Present while committed text names no time that can be picked |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CTimePickerRange
A time range: ISO `HH:mm` ends, either of which may be `null` while only one is typed; an end before the start spans midnight.
export interface CTimePickerRange {
/** The end of the range; earlier than the start for an overnight range. */
end: null | string;
/** The start of the range. */
start: null | string;
}CTimePickerText
The text committed from the field, as typed: a string, or both ends' texts under `range`.
export type CTimePickerText = { end: string; start: string } | string;CTimePickerTexts
UI texts of `c-time-picker`, merged key by key over the AM/PM texts `Intl` gives for the page's `lang` and the English defaults.
export interface CTimePickerTexts {
/** The period before noon in a 12-hour `format`. */
am?: string;
/** Accessible name of the dialog when the field has no label. */
chooseTime?: string;
/** Accessible label of the clear button. */
clearSelection?: string;
/** Accessible label of the close button in the fullscreen panel (narrow viewports). */
closePanel?: string;
/** Label of the Done button in the fullscreen panel (narrow viewports). */
done?: string;
/** Name of the end input and the end tab under `range`. */
end?: string;
/** Accessible name of the hour column. */
hours?: string;
/** Accessible name of the minute column. */
minutes?: string;
/** Label of the Now button (`show-now`). */
now?: string;
/** Accessible label of the clock button. */
openClock?: string;
/** Accessible name of the AM/PM column. */
period?: string;
/** The period from noon in a 12-hour `format`. */
pm?: string;
/** Name of the start input and the start tab under `range`. */
start?: string;
}CTimePickerValue
Value of `c-time-picker`: an ISO `HH:mm` string, a under `range`, or `null` when empty.
export type CTimePickerValue = CTimePickerRange | null | string;CFieldSize shared
Field height of the form controls built on `c-input`. `default` is the 44px field; `small` is the 36px field. Owned here because the value passes from the wrapping control (`c-select`) into `c-input`.
export type CFieldSize = 'default' | 'small';