Public API

Every method on a Timepicker instance is documented here. Methods that touch the dropdown or the committed value return Promise<void> so you can await them in async code.

Instance methods

open(): Promise<void>

Opens the dropdown. A no-op if the picker is already open or has been destroyed.

Before opening, the method:

1. Runs the onBeforeOpen guard (if provided). Cancels if it returns false.
2. Dispatches the cancellable vtp:beforeopen CustomEvent on the input. Cancels if the event is preventDefault()-ed.

await tp.open()

close(reason?: CloseReason): Promise<void>

Closes the dropdown. reason defaults to 'api'. A no-op if the picker is already closed.

await tp.close()
await tp.close('escape')  // programmatically simulate Escape press

Possible CloseReason values: 'select' | 'escape' | 'outside' | 'api'.

toggle(): Promise<void>

Opens the picker if it is closed; closes it if it is open.

await tp.toggle()

setValue(value: string | Date | null): Promise<void>

Sets the picker value programmatically. Goes through the full validation pipeline:

1. Parses the string (or formats the Date) using the active parseStrategy and format.
2. Checks minTime / maxTime. Fires vtp:invalid and returns early if out of range.
3. Runs the validate callback. Fires vtp:invalid and returns early if rejected.
4. Runs the onBeforeChange guard. Returns early if it returns false.
5. Dispatches the cancellable vtp:beforechange CustomEvent. Returns early if prevented.
6. Updates the input value and internal state.
7. Fires onChange / vtp:change.

await tp.setValue('14:30')
await tp.setValue(new Date())    // uses the Date's hours/minutes/seconds
await tp.setValue(null)          // clears the value (when emptyOk is true)
await tp.setValue('')            // same as null

If the value fails parsing or validation, the input is not updated and vtp:invalid fires instead.

clear(): Promise<void>

Shorthand for setValue(null). Clears the value when emptyOk is true (the default).

await tp.clear()

setNow(): Promise<void>

Sets the picker to the current time (new Date()), formatted according to format.

await tp.setNow()

getValue(): string

Returns the current committed value as a formatted string, or '' if no value is set.

const value = tp.getValue()  // e.g. "14:30"

getDate(): Date | null

Returns a Date object representing the selected time, or null if the picker is empty. The date portion is today's date; only the time fields (hours, minutes, seconds) are meaningful.

const d = tp.getDate()
if (d) {
  console.log(d.getHours(), d.getMinutes())
}

isOpen(): boolean

Returns true if the dropdown is currently visible.

if (tp.isOpen()) {
  await tp.close()
}

isValid(): Promise<boolean>

Runs the full validation pipeline (parse + validate callback) against the current value. Returns true if the value is valid or if the picker is empty and emptyOk is true.

if (!await tp.isValid()) {
  form.reportValidity()
}

on(event, handler): () => void

Subscribes to an internal emitter event. Returns an unsubscribe function.

const off = tp.on('vtp:change', (detail) => {
  console.log('new value:', detail.value)
})

// later:
off()  // unsubscribe

See Events for the full list of event names and their payloads.

off(event, handler): void

Removes a specific handler that was added with on. You must pass the same function reference.

const handler = (detail) => console.log(detail)
tp.on('vtp:change', handler)
tp.off('vtp:change', handler)

setOptions(partial: Partial<TimepickerOptions>): void

Merges new options into the live instance. Changes take effect immediately.

tp.setOptions({ minTime: '09:00', maxTime: '18:00' })
tp.setOptions({ locale: 'de' })

• Callbacks are live. Every onX option is read at the moment the event fires, so setOptions({ onClose }) registers a callback that wasn't passed to the constructor, and setOptions({ onClose: undefined }) removes one that was.
• An open dropdown is rebuilt. minTime, maxTime, format, locale, the step options and the footer buttons apply without closing the picker. The rebuild returns the dropdown to its main spinner view — an open hour/minute grid is dismissed.
• minTime/maxTime re-validate the current value. If the value falls outside the new range, vtp:invalid fires with BELOW_MIN/ABOVE_MAX and the input gets the vtp-invalid class. The value itself is kept — narrowing a range never silently wipes what the user entered. Clear it yourself if that's what you want.

A few options are consumed once during construction and cannot be changed this way: value, defaultValue, openOnFocus, allowManualInput.

focus(): void

Focuses the underlying <input> element. If openOnFocus is true, this will also open the dropdown.

tp.focus()

destroy(): void

Tears down the picker completely:

• Closes the dropdown if open.
• Removes all event listeners attached to the input.
• Removes ARIA attributes (role, aria-haspopup, aria-expanded).
• Removes the vtp-input CSS class.
• Fires vtp:destroy on the input.

After destroy(), the Timepicker instance is inert. Do not call any other methods on it.

tp.destroy()

Always call destroy() before removing the input from the DOM to prevent memory leaks.

Static methods

Timepicker.getInstance(el): Timepicker | null

Returns the Timepicker instance attached to a given element, or null if none exists. Accepts either an HTMLInputElement or a CSS selector string.

// retrieve by CSS selector
const tp = Timepicker.getInstance('#departure')
tp?.setValue('14:30')

// retrieve by element reference
const input = document.getElementById('departure') as HTMLInputElement
const value = Timepicker.getInstance(input)?.getValue()

Returns null when:

• no picker has been created for the element
• the picker has already been destroyed

TIP

This is useful in event handlers, third-party integrations, or any context where you don't hold the original Timepicker reference.

Timepicker.setDefaults(partial): void

Sets global default options for all future instances. See Initialization.

Timepicker.setDefaults({ locale: 'sk', minuteStep: 15 })

Timepicker.autoInit(selector?): Timepicker[]

Finds all elements matching selector (default: [data-timepicker]) and creates a Timepicker for each one. Options are read from the element's data-timepicker-options attribute as JSON.

<input data-timepicker data-timepicker-options='{"format":"HH:mm:ss","showNowButton":true}' />

const pickers = Timepicker.autoInit() // returns Timepicker[]

See the Auto-Init cookbook for a complete example.

Timepicker.parse(text, opts?): string | null

Parses a raw string into a formatted time string without creating a picker instance. Returns null if parsing fails.

Timepicker.parse('930')           // "09:30" (right-fill, default)
Timepicker.parse('930', { strategy: 'left-fill' })   // "09:30"
Timepicker.parse('93000', { strategy: 'right-fill', hasSeconds: true }) // "09:30:00"
Timepicker.parse('abc')           // null

Timepicker.format(date, format?): string

Formats a Date object into a time string.

Timepicker.format(new Date(), 'HH:mm')    // "14:30"
Timepicker.format(new Date(), 'hh:mm a')  // "02:30 PM"