Components

TimePickerField

A form field to pick a time, either as an input that opens a time picker popup or as an inline time picker, with label, help text and validation.

Component

View code

Show playground

Label (optional)

Help text example

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	—	`string`
`ariaLabel`	—	—	`string`
`helpText`	—	—	`string`
`helpTextPosition`	—	`Position.BOTTOM`	`Position`
`variant`	—	`PickerVariant.INPUT`	`PickerVariant`
`modelValue`	—	`null`	`string \| null`
`placeholder`	—	—	`string`
`icon`	—	—	`string`
`size`	—	`InputSize.MD`	`InputSize`
`clearable`	—	`true`	`boolean`
`pickerPosition`	—	`Position.BOTTOM`	`Position`
`autoFlip`	—	`true`	`boolean`
`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`
`validator`	—	`() => null`	`(value: unknown) => string \| null`
`error`	—	`''`	`string`
`disabled`	—	`false`	`boolean`
`readonly`	—	`false`	`boolean`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`transparent`	—	`false`	`boolean`
`clearAriaLabel`	—	—	`string`
`openAriaLabel`	—	—	`string`
`glowColorMode`	—	`GlowColorMode.NONE`	`GlowColorMode`
`glowTrigger`	—	`GlowTrigger.FOCUS`	`GlowTrigger`
`glowType`	—	`GlowType.INNER`	`GlowType`
`glowOpacity`	—	`40`	`number`
`glowSize`	—	—	`number`

Usage

id

Sets the id of the input (and the for of the label). Required.

 <template>
    <TimePickerField id="start-time" />
</template>

Type: string

label

Sets the label shown above the field. In the INLINE variant it also names the time picker.

 <template>
    <TimePickerField id="time" label="Starts at" />
</template>

Type: string

ariaLabel

Sets the accessible name when there is no visible label.

 <template>
    <TimePickerField id="time" ariaLabel="Start time" />
</template>

Type: string

helpText

Sets the help text. When there is an error, the error is shown instead.

 <template>
    <TimePickerField id="time" helpText="Local time" />
</template>

Type: string

helpTextPosition

Sets where the help text is shown, via the Position enum.

 <template>
    <TimePickerField id="time" :helpTextPosition="Position.TOP" helpText="Hint" />
</template>

Type: Position
Default: Position.BOTTOM

Options

Value	Description
`TOP`	top
`BOTTOM`	bottom

variant

Sets how the time picker is shown via the PickerVariant enum. INPUT shows a field that opens the time picker in a popup, and INLINE shows the time picker itself in place of the field. The label, help text and error are shown in both.

 <template>
    <TimePickerField id="time" :variant="PickerVariant.INLINE" label="Starts at" />
</template>

Type: PickerVariant
Default: PickerVariant.INPUT

Options

Value	Description
`INPUT`	input
`INLINE`	inline

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>
    <TimePickerField id="time"  v-model="time" />
</template>

Type: string | null
Default: null

placeholder

Sets the placeholder of the input. Falls back to useDSConfig().timePicker.placeholderText(). Only applies to the INPUT variant.

 <template>
    <TimePickerField id="time" placeholder="Choose a time" />
</template>

Type: string

icon

Sets an icon shown at the start of the input. Only applies to the INPUT variant.

 <template>
    <TimePickerField id="time" icon="mdi:alarm" />
</template>

Type: string

size

Sets the height of the input via the InputSize enum. Only applies to the INPUT variant.

 <template>
    <TimePickerField id="time" :size="InputSize.LG" />
</template>

Type: InputSize
Default: InputSize.MD

Options

Value	Description
`MD`	md
`LG`	lg

clearable

Shows a button to clear the value while there is one.

 <template>
    <TimePickerField id="time" :clearable="false" />
</template>

Type: boolean
Default: true

pickerPosition

Sets whether the popup opens below or above the input, via the Position enum.

 <template>
    <TimePickerField id="time" :pickerPosition="Position.TOP" />
</template>

Type: Position
Default: Position.BOTTOM

Options

Value	Description
`TOP`	top
`BOTTOM`	bottom

autoFlip

Moves the picker to the other side when it does not fit in the window. If it would be cut off at the bottom or the top edge of the screen and there is more room on the other side, it opens there instead. The position is checked when it opens, and pickerPosition is only the starting point. Set it to false to always keep the position as given.

 <template>
    <TimePickerField v-model="time" id="time" :autoFlip="false" />
</template>

Type: boolean
Default: true

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>
    <TimePickerField id="time"  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>
    <TimePickerField id="time"  :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>
    <TimePickerField id="time"  :hasSeconds="true" />
</template>

Type: boolean
Default: false

minuteStep

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

 <template>
    <TimePickerField id="time"  :minuteStep="15" />
</template>

Type: number
Default: 1

secondStep

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

 <template>
    <TimePickerField id="time"  :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>
    <TimePickerField id="time"  min="09:00" />
</template>

Type: string

max

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

 <template>
    <TimePickerField id="time"  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>
    <TimePickerField id="time"  :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>
    <TimePickerField id="time"  :isRounded="true" />
</template>

Type: boolean
Default: false

isBoxed

Adds the border, background and padding to the time picker. Only applies to the INLINE variant, since the popup is always boxed.

 <template>
    <TimePickerField id="time" :variant="PickerVariant.INLINE" :isBoxed="false" />
</template>

Type: boolean
Default: true

validator

Validates the value and returns an error message, or null. It runs only when the field is required, whenever the value changes and when the popup closes.

 <template>
    <TimePickerField id="time" required :validator="validateField" />
</template>

Type: (value: unknown) => string | null
Default: () => null

error

Sets the error message. The field and the help text switch to the error style.

 <template>
    <TimePickerField id="time" error="Required field" />
</template>

Type: string
Default: ''

disabled

Disables the field and the time picker.

 <template>
    <TimePickerField id="time" :disabled="true" />
</template>

Type: boolean
Default: false

readonly

Shows the value without letting the user change it. The popup does not open.

 <template>
    <TimePickerField id="time" :readonly="true" />
</template>

Type: boolean
Default: false

required

Marks the field as required: hides the optional label and enables the validator.

 <template>
    <TimePickerField id="time" label="Time" :required="true" />
</template>

Type: boolean
Default: false

showOptionalLabel

Shows the optional text next to the label when the field is not required.

 <template>
    <TimePickerField id="time" label="Time" :showOptionalLabel="false" />
</template>

Type: boolean
Default: true

optionalLabel

Sets the optional text. Falls back to useDSConfig().forms.optionalLabelText().

 <template>
    <TimePickerField id="time" label="Hora" optionalLabel="(opcional)" />
</template>

Type: string

transparent

Removes the background of the input.

 <template>
    <TimePickerField id="time" :transparent="true" />
</template>

Type: boolean
Default: false

clearAriaLabel

Sets the aria-label of the clear button. Falls back to useDSConfig().forms.clearSelectionText().

 <template>
    <TimePickerField id="time" clearAriaLabel="Borrar hora" />
</template>

Type: string

openAriaLabel

Sets the aria-label of the clock button. Falls back to useDSConfig().timePicker.openText().

 <template>
    <TimePickerField id="time" openAriaLabel="Abrir selector de hora" />
</template>

Type: string

glowColorMode

Draws a glow around the time input box only. The label and the help text do not glow. It is shown in light mode, dark mode, both or none, and it uses the GlowColorMode enum. It is GlowColorMode.NONE by default, so the field has no glow until you turn it on.

The glow uses the brand color and turns to the error color when the field has an error.

 <template>
    <TimePickerField :glowColorMode="GlowColorMode.DARK" />
</template>

Type: GlowColorMode
Default: GlowColorMode.NONE (set by the DS config, see Configuration)

Options

Value	Description
`NONE`	No glow.
`BOTH`	Glow in light and dark mode.
`LIGHT`	Glow in light mode only.
`DARK`	Glow in dark mode only.

glowTrigger

Sets when the glow appears. It uses the GlowTrigger enum and works together with glowColorMode, which decides in which theme the glow shows. It is GlowTrigger.FOCUS by default.

FOCUS shows the glow while the field has focus. On touch screens there is no hover, so with HOVER the glow never shows.

 <template>
    <TimePickerField :glowColorMode="GlowColorMode.BOTH" :glowTrigger="GlowTrigger.FOCUS" />
</template>

Type: GlowTrigger
Default: GlowTrigger.FOCUS (set by the DS config, see Configuration)

Options

Value	Description
`ALWAYS`	The glow is always visible.
`HOVER`	The glow shows while the pointer is over the field.
`FOCUS`	The glow shows while the field has focus.
`HOVER_FOCUS`	The glow shows on hover and on focus.

glowType

Sets where the glow is drawn. It uses the GlowType enum and works together with glowColorMode. It is GlowType.INNER by default.

 <template>
    <TimePickerField :glowColorMode="GlowColorMode.BOTH" :glowType="GlowType.INNER" />
</template>

Type: GlowType
Default: GlowType.INNER (set by the DS config, see Configuration)

Options

Value	Description
`OUTER`	The glow spreads around the outside of the element.
`INNER`	The glow is drawn inside the element, along its edges.

glowOpacity

Sets how strong the glow is, from 0 (invisible) to 100 (full color). The default is 40. Values move in steps of 5, so 42 is rounded to 40. It has no effect while glowColorMode is GlowColorMode.NONE.

 <template>
    <TimePickerField :glowColorMode="GlowColorMode.BOTH" :glowOpacity="30" />
</template>

Type: number
Default: 40 (set by the DS config, see Configuration)

glowSize

Sets how far the glow spreads, in pixels. It is null by default, so each component keeps its own size (for example, buttons follow their size). Values move in steps of 2 from 0 to 64, so 13 is rounded to 14. It has no effect while glowColorMode is GlowColorMode.NONE.

 <template>
    <TimePickerField :glowColorMode="GlowColorMode.BOTH" :glowSize="32" />
</template>

Type: number
Default: null (set by the DS config, see Configuration)

Accessibility

In the INPUT variant the field is a read-only text input with aria-haspopup="dialog" and aria-expanded. Focus moves into the time picker when it opens and returns to the input when it closes.

Value	Description
`Enter / Space / ArrowDown`	Opens the time picker from the input.
`Escape`	Closes the time picker and returns the focus to the input.

The popup stays open after a pick, since a time takes an hour and a minute. Close it with Escape or by clicking outside. See the TimePicker accessibility notes for the keys inside it.

Emits

Value	Description
`@update:modelValue`	Emitted with the new time (`HH:mm` or `HH:mm:ss`) when it changes, or `null` when it is cleared.
`@update:error`	Emitted with the validation message, or an empty string, when the validator runs.

Example

 <template>
    <TimePickerField :modelValue="time" id="time" @update:modelValue="handleChange" />
</template>

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

const handleChange = (value: string | null) => {
    time.value = value
}
</script>

Methods

Value	Description
`open()`	Opens the popup. Does nothing when the field is disabled, readonly or inline.
`close()`	Closes the popup and returns the focus to the input.