Select

Selects expose a constrained list of options while keeping the closed trigger aligned with surrounding field controls.

Basic Usage

Use a trigger plus content list for the common closed-select pattern.

Sizes

The select trigger follows the same sizing rhythm as other form controls so it can sit cleanly beside inputs, buttons, and other CP fields.

Widths

Select triggers use their content width by default. Add a width utility to the trigger when the control should be fixed-width or fill its parent.

Grouped Options

Labels and separators help when a single list includes more than one logical option set.

Decorations

Host start / end slots decorate the closed trigger (icons, status dots, and similar).

Status Options

Put Status in an option’s start slot when the list represents Craft-like statuses.

API

Select

Slots

Name	Description
start	Presentational decoration before the trigger label (e.g. icons)
end	Presentational decoration before the expand chevron
(default)	pk-option and pk-option-group items

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	Emitted when the selection changes. 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-popup	Positioned listbox panel host.

Option

Slots

Name	Description
start	Presentational decoration before the label (e.g. pk-status).
(default)	Option label

Props

Name	Description
disabled	Disables the option so it cannot be selected. Type boolean Default false
focusIndex	Type number Default -1
hidden	Hides the option from the list (e.g. filtered combobox results). Type boolean Default false
highlighted	Keyboard / pointer highlight within the listbox. Type boolean Default false
label	Optional short label for the closed trigger / filter identity (v1 itemToStringLabel). When set, preferred over concatenating rich default-slot text (title + subtitle). Type string
matchQuery	When set, the label renders with matching query text highlighted (combobox filter). Type string
optionId	Type string
selected	Whether this option is currently selected. Type boolean Default false
value	Option value submitted / emitted when selected. Type string

Methods

Name	Description
focusControl(preventScroll)	Focus the option’s inner control (listbox keyboard navigation).
getLabel()	Label for the closed combobox/select value. Prefers the label attribute when set; otherwise default-slot text (excluding slot="start"), joined with spaces for multi-node layouts.

Events

Name	Description
@pk-option-highlight	Emitted when the option becomes the highlighted item.
@pk-option-select	Emitted when the option is activated (click / Enter).

CSS Parts

Name	Description	CSS selector
check	Selected-state check indicator	::part(check)
label	Option label	::part(label)
option	Option button	::part(option)
start	Start decoration container	::part(start)

OptionGroup

Slots

Name	Description
(default)	pk-option items in this group

Props

Name	Description
hidden	Hides the group and its options. Type boolean Default false
label	Visible group heading above the options. Type string

CSS Parts

Name	Description	CSS selector
label	Group label	::part(label)