Time Picker

Time pickers provide a compact controlled input for choosing one time value.

Basic Usage

Use a controlled value when the selected time needs to stay in sync with broader form state.

Empty State

An empty placeholder is useful when the time should be chosen explicitly rather than prefilled.

States

Show invalid and disabled states when the picker is used inside forms.

API

Slots

Name	Description
start	Overrides the default clock icon
(default)	Additional pk-option items append after the generated list
end	Presentational decoration before the expand chevron

Props

Name	Description
ariaLabel	Accessible name for the trigger when no visible label is present. Type string | null Default null
clearable	Alias of with-clear — shows a clear control when the value is non-empty. Type boolean Default false
customError	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue	Initial value before user interaction (form reset baseline). Type string
defaultValues	Initial multi values before user interaction. Property-only. Type string[] Default []
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
invalid	Marks the control invalid (visual + ARIA). Type boolean Default false
isInvalid	Alias for invalid.
loopFocus	Whether arrow-key focus loops from the last option back to the first (and vice versa). Base UI Select has no equivalent; default: false. Type boolean Default false
multiple	Allow more than one option to be selected (tag display). Type boolean Default false
name	Name submitted with form data. Type string | null Default null
open	Whether the listbox is open. Prefer show() / hide() for animated transitions. Type boolean Default false
placeholder	Prompt shown when nothing is selected. Empty by default. Type string
placement	Preferred listbox placement; may flip to stay in viewport. Type PkPopupPlacement Default bottom-start
required	Marks the control as required for form submission. Type boolean Default false
sideOffset	Gap between the trigger and listbox panel in px. Type number Default 4
size	Shared CP size scale for the closed trigger and list items. Type PkSelectSize Default default
value	Selected value (single-select). Empty string when cleared. Type string
values	Selected values when multiple is set. Property-only (not an attribute). Type string[] Default []
width	When full, the trigger stretches to the host width. Type 'full' | undefined
withClear	Shows a clear control when the value is non-empty. Type boolean Default false

Methods

Name	Description
checkValidity()	Runs constraint validation without showing the browser UI.
hide(source: PkOverlaySource)	Closes the listbox.
reportValidity()	Runs constraint validation and shows the browser UI when invalid.
resetValidity()	Clears custom errors and re-syncs validity state.
setCustomValidity(message: string)	Sets or clears a custom validation message.
show()	Opens the listbox.

Events

Name	Description
@change	Native change event when the selection changes.
@input	Native input event when the selection changes.
@pk-after-hide	Emitted after the listbox closes and exit motion finishes.
@pk-after-show	Emitted after the listbox opens and enter motion finishes.
@pk-change	detail.value Type { value: string, values: string[] }
@pk-clear	Emitted when the value is cleared via the clear control.
@pk-hide	Emitted when the listbox begins to close (cancelable). Type { source: string }
@pk-invalid	Emitted when constraint validation fails.
@pk-open-change	Emitted when open changes after show/hide settles. Type { open: boolean }
@pk-show	Emitted when the listbox begins to open.

CSS Custom Properties

Name	Description
--pk-select-anchor-width	Panel min-width; set from the trigger width while open.
--pk-select-decoration-size	Start/end decoration glyph size. Default 0.875rem
--pk-select-fill	Closed trigger background. Default var(--pk-color-slate-250)
--pk-select-fill-hover	Closed trigger hover background. Default var(--pk-color-slate-300)

Custom States

Name	Description	CSS selector
disabled	The control is disabled.	:state(disabled)
invalid	The control currently fails constraint validation.	:state(invalid)
optional	The control is not required.	:state(optional)
required	The control is required.	:state(required)
user-invalid	Invalid after the user has interacted with the control.	:state(user-invalid)
user-valid	Valid after the user has interacted with the control.	:state(user-valid)
valid	The control currently passes constraint validation.	:state(valid)

CSS Parts

Name	Description	CSS selector
control	Trigger control wrapper	::part(control)
end	Host end decoration container	::part(end)
panel	Listbox panel	::part(panel)
start	Host start decoration container	::part(start)
trigger	Select trigger button	::part(trigger)
trigger-start	Mirrored start decoration from the selected option	::part(trigger-start)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-option	—