Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

TimePicker

A compact custom time picker with step-aware hour, minute, and second lists.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add time-picker

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import TimePicker from './components/ui/time-picker/TimePicker.vue'

const time = ref('')
</script>

<template>
  <label for="appointment-time">Appointment time</label>
  <TimePicker
    id="appointment-time"
    v-model="time"
    name="time"
    min="09:00"
    max="17:00"
    :step="900"
    :messages="{
      timePickerLabel: 'Choose an appointment time',
      chooseTime: 'Choose time',
      hoursLabel: 'Hours',
      minutesLabel: 'Minutes',
      secondsLabel: 'Seconds',
      clearSelection: 'Clear time',
    }"
  />
</template>

The custom lists support arrows, Home/End, and Escape, while an off-screen native time control preserves form serialization and constraints. Seconds appear when the value or step requires them.

When to use it

Office hours

Choose a wall-clock time in a bounded daily interval.

Meeting start

Present a localized time while storing a canonical HH:mm value.

More examples

Quarter-hour appointment

step is seconds, so 900 gives 15-minute choices.

Quarter-hour appointment
<script setup lang="ts">
import { ref } from 'vue'
import TimePicker from './components/ui/time-picker/TimePicker.vue'

const time = ref('')
const messages = {
  timePickerLabel: 'Choose appointment time',
  chooseTime: 'Choose time',
  hoursLabel: 'Hours',
  minutesLabel: 'Minutes',
  secondsLabel: 'Seconds',
  clearSelection: 'Clear time',
}
</script>
<template>
  <label for="appointment-time">Appointment time</label>
  <TimePicker
    id="appointment-time"
    v-model="time"
    name="time"
    min="09:00"
    max="17:00"
    :step="900"
    locale="en-GB"
    :messages="messages"
  />
</template>

US local meeting time

Locale affects display, while an IANA zone belongs to the event record.

US local meeting time
<script setup lang="ts">
import { ref } from 'vue'
import TimePicker from './components/ui/time-picker/TimePicker.vue'

const time = ref('09:30')
const timeZone = ref('America/New_York')
const messages = {
  timePickerLabel: 'Choose meeting time',
  chooseTime: 'Choose time',
  hoursLabel: 'Hours',
  minutesLabel: 'Minutes',
  secondsLabel: 'Seconds',
  clearSelection: 'Clear time',
}
</script>
<template>
  <label for="meeting-time">Meeting time in New York</label>
  <TimePicker id="meeting-time" v-model="time" locale="en-US" :messages="messages" />
  <input type="hidden" name="timeZone" :value="timeZone">
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

TimePicker

Complete API for TimePicker
NameType or signatureDefaultWhat it does
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
minpropstring | undefinedNot setSmallest allowed value.
maxpropstring | undefinedNot setLargest allowed value.
steppropnumber | undefined60Amount added or removed for each adjustment.
localepropstring | undefinedNot setChoose the language and regional formatting for dates or text.
messagespropTimePickerMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelstring | undefined""Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: string]—Requests a new model value from the parent.
errorslot{ message: string; messages: string[]; }OptionalContent for the error area of TimePicker.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
triggerElementexposedHTMLButtonElement | null—Access trigger element from a component template ref.
focusexposed() => void | undefined—Move keyboard focus to this control.
showPickerexposed() => void—Access show picker from a component template ref.
openexposed() => void—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.
Public type definitions
Public types
// packages/frameworks/vue/components/time-picker/types.ts
import type { ControlSize } from '@getweini/vue/types'

export interface TimePickerMessages {
  timePickerLabel: string
  chooseTime: string
  hoursLabel: string
  minutesLabel: string
  secondsLabel: string
  clearSelection: string
}

export interface TimePickerProps {
  id?: string
  name?: string
  form?: string
  size?: ControlSize
  invalid?: boolean
  disabled?: boolean
  readonly?: boolean
  required?: boolean
  min?: string
  max?: string
  step?: number
  locale?: string
  messages: TimePickerMessages
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The model stores HH:mm or HH:mm:ss, not a timezone-aware instant. step uses seconds.
  • For an event, store date, time, and IANA timezone separately; resolve daylight-saving ambiguity when creating the instant.

Accessibility and localization

  • Localize all panel labels and clear text. Name the time control and include the timezone in nearby help when it matters.

Source contract and editing guidance