CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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

Basic
Vue React Angular TypeScript
<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>
Min max
Vue React Angular TypeScript
<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>
Minute step
Vue React Angular TypeScript
<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>
Now
Vue React Angular TypeScript
<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>
Range
Vue React Angular TypeScript
<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>
Texts
Vue React Angular TypeScript
<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>
Twelve hour
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
clearableclearablebooleanfalse Make the value clearable
disableddisabledbooleanfalse Disable the field
errorMessageerror-messagestring'' Error message shown in place of the hint while the field is invalid
formatformatstring'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`
hideMessagehide-messagebooleanfalse app default Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the field
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
labellabelstring'' Element label
labelOnToplabel-on-topbooleanfalse app default Label on top of the field
maxmaxstring'' The latest time that can be picked or typed, as an ISO `HH:mm` time
minminstring'' 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
minuteStepminute-stepnumber1 Minutes between the minute column's rows; typed times need not fall on the step
namenamestring'' The name the time submits under in a native `<form>`, as its ISO text; a `range` as one ISO 8601 interval, `start/end`
placeholderplaceholderstring'' Placeholder of the input; the `format` pattern when empty
rangerangebooleanfalse Pick a range: the value becomes `{ start, end }` and the field holds two inputs
requiredrequiredbooleanfalse Set the field as required
shadowshadowbooleanfalse app default Shadow variant
showNowshow-nowbooleanfalse app default Show a Now button under the columns that commits the current time
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box
texts—CTimePickerTexts{} 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
valuevalueCTimePickerValuenull The time as an ISO `HH:mm` string on a 24-hour clock, or `{ start, end }` under `range`; `null` when empty
hideDetails deprecated hide-detailsbooleanfalse 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

EventDetailDescription
changeCTimePickerValueFired 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:textCTimePickerTextFired 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.
inputvoidNative bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail.
update:valueCTimePickerValueFired alongside `change` with the same detail — the `v-model` contract.

Methods

MethodSignatureDescription
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): voidFocus 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.

PartDescription
inputThe text input; under `range` both the start and the end input
separatorThe dash between the start and end inputs under `range`
panelThe top-layer popover container anchored below the field
cardThe dialog surface inside the panel holding the columns
heading-rowThe top row of the fullscreen panel (narrow viewports): the field label as heading and the close button
headingThe field label naming the fullscreen panel
closeThe close button of the fullscreen panel
end-switchThe Start | End switch above the columns under `range`
endOne end's button in the end switch
columnsThe row of time columns
columnOne time column: hours, minutes or AM/PM
optionOne row of a time column
actionsThe row under the columns holding the Now button (`show-now`) and, in the fullscreen panel, the Done button
nowThe Now button: commits the current time
doneThe Done button of the fullscreen panel (narrow viewports): commits what the panel holds and closes
messageThe 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.

StateDescription
bad-inputPresent 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';