Combobox

Comboboxes mix freeform search with constrained option selection.

Input Mode

Input mode works well when the control should feel like a searchable text field with inline suggestions.

Sizes

The combobox input and option list follow the same sizing rhythm as select so searchable controls can align with adjacent fields.

Widths

Combobox input controls use their content width by default. Add a width utility to the input when the control should be fixed-width or fill its parent.

Popup Mode

Popup mode is a better fit when the trigger should behave more like a select than a text field.

Multiple Selection

Chips are useful when the chosen options need to remain visible after selection.

Grouped Options

Grouped content is useful when the option list should be organized into labeled collections.

Allow Create

allowCreate offers creating a new option when the typed query isn’t already in the list.

Custom Values

allowCustomValue lets a single-select keep typed text that doesn’t match an option.

Higher-Level Input API

Combobox covers the common single-select and async loading cases — static Option children for local lists, or async + fetchOptions when results come from a remote search.

Async Search

Set async and assign fetchOptions={(query, signal) => ...} (a JS property) so options load as the user types. No static Option children are needed — the control owns loading and empty states.

API

Slots

Name	Description
start	Presentational decoration before the input (e.g. icons)
end	Presentational decoration before the expand/clear controls
(default)	pk-option and pk-option-group items

Props

Name	Description
allowCreate	Type boolean Default false
allowCustomValue	Type boolean Default false
ariaLabel	Type string | null Default null
async	When true, options are loaded via fetchOptions as the user types instead of filtering static pk-option children. Type boolean Default false
autoHighlight	When true, the first matching option is highlighted on open or when filtering. Type boolean Default false
clearable	Type boolean Default false
customError	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue	Type string
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
emptyMessage	Type string Default No options found.
fetchOptions	Remote search handler — (query, signal) => Promise<options>. Type PkComboboxFetchHandler | null Default null
filter	Custom filter — (option, query) => boolean. Defaults to label/value substring match. Type PkComboboxFilter | null Default null
instructions	Type string
invalid	Type boolean Default false
isInvalid	Alias for invalid.
label	Type string
loadingMessage	Message shown while async results are loading. Type string Default Searching…
loopFocus	Whether arrow-key focus loops from the last option back to the first (and vice versa). Mirrors Base UI Combobox — default: true. Type boolean Default true
multiple	Type boolean Default false
name	Name submitted with form data. Type string | null Default null
open	Type boolean Default false
placeholder	Empty by default — consumers opt in when a prompt is useful. Type string
placement	Type PkPopupPlacement Default bottom-start
popupMode	When true, the control shows a trigger button and the search field renders inside the popup. Type boolean Default false
required	Marks the control as required for form submission. Type boolean Default false
searchPlaceholder	Type string Default Search
sideOffset	Gap between the control and listbox panel in px (default: 6). Type number Default 6
size	Type PkComboboxSize Default default
startTypingMessage	Message shown before the user types in async mode. Type string Default Start typing to search…
value	Type string
width	When full, the control stretches to the host width. Type 'full' | undefined
withClear	Type boolean Default false

Methods

Name	Description
checkValidity()	Runs constraint validation without showing the browser UI.
hide(source: PkOverlaySource)	—
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()	—

Events

Name	Description
@change	—
@input	—
@pk-change	—
@pk-create	Cancelable. Fired before a new option is created when allow-create is enabled.
@pk-open-change	—

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
async-status	Async search status message	::part(async-status)
clear-button	Clear selection button	::part(clear-button)
control	Input control wrapper	::part(control)
empty	Empty-state message	::part(empty)
end	Host end decoration container	::part(end)
expand-button	Toggle listbox button	::part(expand-button)
input	Combobox text input	::part(input)
panel-body	Scrollable listbox region inside the popup panel	::part(panel-body)
panel-input	Popup-mode search input	::part(panel-input)
panel-search	Popup-mode search field container	::part(panel-search)
start	Host start decoration container	::part(start)
tag	Individual multiselect chip	::part(tag)
tag-remove	Chip remove button	::part(tag-remove)
tags	Multiselect chip container	::part(tags)
trigger	Popup-mode trigger button (shows the selected value)	::part(trigger)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-popup	—