Components

TimePicker

Displays columns of hours, minutes, seconds and AM/PM to pick a time, with 12 or 24 hour clocks, steps, limits and keyboard navigation.

Component

View code

Show playground

Props

Props	Default	Type
`modelValue`	`null`	`string \| null`
`locale`	`'en-US'`	`string`
`hourFormat`	—	`HourFormat`
`hasSeconds`	`false`	`boolean`
`minuteStep`	`1`	`number`
`secondStep`	`1`	`number`
`min`	—	`string`
`max`	—	`string`
`color`	`ColorAccent.PRIMARY_BRAND`	`ColorAccent`
`isRounded`	`false`	`boolean`
`isBoxed`	`true`	`boolean`
`disabled`	`false`	`boolean`
`readonly`	`false`	`boolean`
`ariaLabel`	—	`string`
`hoursAriaLabel`	—	`string`
`minutesAriaLabel`	—	`string`
`secondsAriaLabel`	—	`string`
`periodAriaLabel`	—	`string`

Usage

modelValue

Sets the selected time as HH:mm, or HH:mm:ss when hasSeconds is on. Always 24-hour, whatever hourFormat shows. Bind it with v-model.

 <template>
    <TimePicker  v-model="time" />
</template>

Type: string | null
Default: null

locale

Sets the BCP 47 locale used to write the time and the AM/PM text, and to choose the 12 or 24 hour clock when hourFormat is not set.

 <template>
    <TimePicker  locale="es-ES" />
</template>

Type: string
Default: 'en-US'

hourFormat

Sets the 12 or 24 hour clock via the HourFormat enum. Defaults to the clock of the locale. The 12-hour clock adds an AM/PM column.

 <template>
    <TimePicker  :hourFormat="HourFormat.HOURS_12" />
</template>

Type: HourFormat

Options

Value	Description
`HOURS_12`	12
`HOURS_24`	24

hasSeconds

Adds a seconds column and makes the value HH:mm:ss.

 <template>
    <TimePicker  :hasSeconds="true" />
</template>

Type: boolean
Default: false

minuteStep

Sets the interval between the minutes, from 1 to 30.

 <template>
    <TimePicker  :minuteStep="15" />
</template>

Type: number
Default: 1

secondStep

Sets the interval between the seconds, from 1 to 30.

 <template>
    <TimePicker  :hasSeconds="true" :secondStep="15" />
</template>

Type: number
Default: 1

min

Sets the earliest selectable time (HH:mm). Hours, minutes and seconds before it are disabled.

 <template>
    <TimePicker  min="09:00" />
</template>

Type: string

max

Sets the latest selectable time (HH:mm). Hours, minutes and seconds after it are disabled.

 <template>
    <TimePicker  max="17:30" />
</template>

Type: string

color

Sets the accent color of the selected options and the focus ring. Supports PRIMARY_BRAND and SECONDARY_BRAND.

 <template>
    <TimePicker  :color="ColorAccent.SECONDARY_BRAND" />
</template>

Type: ColorAccent
Default: ColorAccent.PRIMARY_BRAND

Options

Value	Description
`PRIMARY_BRAND`	primary-brand
`SECONDARY_BRAND`	secondary-brand

isRounded

Makes the options fully round.

 <template>
    <TimePicker  :isRounded="true" />
</template>

Type: boolean
Default: false

isBoxed

Adds the border, background and padding. Turn it off to embed the time picker inside another surface.

 <template>
    <TimePicker v-model="time" :isBoxed="false" />
</template>

Type: boolean
Default: true

disabled

Disables every option.

 <template>
    <TimePicker v-model="time" :disabled="true" />
</template>

Type: boolean
Default: false

readonly

Keeps the value fixed while still showing it. The columns are marked with aria-readonly.

 <template>
    <TimePicker v-model="time" :readonly="true" />
</template>

Type: boolean
Default: false

ariaLabel

Sets the accessible name of the time picker.

 <template>
    <TimePicker v-model="time" ariaLabel="Start time" />
</template>

Type: string

hoursAriaLabel

Sets the accessible name of the hours column. Falls back to useDSConfig().timePicker.hoursText().

 <template>
    <TimePicker v-model="time" hoursAriaLabel="Horas" />
</template>

Type: string

minutesAriaLabel

Sets the accessible name of the minutes column. Falls back to useDSConfig().timePicker.minutesText().

 <template>
    <TimePicker v-model="time" minutesAriaLabel="Minutos" />
</template>

Type: string

secondsAriaLabel

Sets the accessible name of the seconds column. Falls back to useDSConfig().timePicker.secondsText().

 <template>
    <TimePicker v-model="time" :hasSeconds="true" secondsAriaLabel="Segundos" />
</template>

Type: string

periodAriaLabel

Sets the accessible name of the AM/PM column. Falls back to useDSConfig().timePicker.periodText().

 <template>
    <TimePicker v-model="time" :hourFormat="HourFormat.HOURS_12" periodAriaLabel="a. m. / p. m." />
</template>

Type: string

Accessibility

The time picker is a group with one listbox per column (hours, minutes, seconds and AM/PM). Each value is an option with aria-selected, and each column has one tab stop: the selected option, or the first enabled one. Set ariaLabel so the group has a name.

Value	Description
`ArrowUp / ArrowDown`	Moves to the previous or next option of the column.
`Home / End`	Moves to the first or last option of the column.
`ArrowLeft / ArrowRight`	Moves to the selected option of the previous or next column.
`Enter / Space`	Selects the focused option.

Options outside min and max are disabled, so they cannot be focused.

Emits

Value	Description
`@update:modelValue`	Emitted with the new time (`HH:mm` or `HH:mm:ss`) when an option is selected. When there is no value yet, the other parts start at `00`.

Example

 <template>
    <TimePicker :modelValue="time" @update:modelValue="handleSelect" />
</template>

<script setup lang="ts">
const time = ref<string | null>(null)

const handleSelect = (value: string) => {
    time.value = value
}
</script>

Methods

Value	Description
`focus()`	Moves the focus to the selected hour (or the first enabled one) so keyboard navigation can start.