Autocomplete

Freeform text with optional suggestions. The committed value is the input text — choosing a suggestion inserts it; any typed value is valid.

Consumers supply pk-option children (or async + fetchOptions).

Prefer Autocomplete when the typed text is the value and suggestions only help complete it. Prefer Combobox when the field stores a selected option (and typing is just for filtering) — not freeform custom text.

Basic

Focus the field and type to filter, or pick a suggestion. Keep typing past a suggestion — freeform values stay committed.

Clearable

Grouped suggestions

Organize suggestions with labeled option groups when the list benefits from sections.

Async suggestions

Remote (or plugin) search via async + fetchOptions. Typing still commits freely; results only help complete the value.

With Field warning

Existence checks belong to the plugin. The field can show a soft warning while still saving a path that does not exist yet.

API

Slots

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

Attributes & Properties

Name	Description
ariaLabel aria-label	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 auto-highlight	When true, the first matching option is highlighted on open or when filtering. Type boolean Default false
clearable	Type boolean Default false
customError custom-error	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue default-value	Type string
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
emptyMessage empty-message	Type string Default No options found.
fetchOptions	Remote search handler — (query, signal) => Promise<options>. Type PkAutocompleteFetchHandler | null Default null
filter	Custom filter — (option, query) => boolean. Defaults to label/value substring match. Type PkAutocompleteFilter | null Default null
instructions	Type string
invalid	Type boolean Default false
label	Type string
loadingMessage loading-message	Message shown while async results are loading. Type string Default Searching…
loopFocus loop-focus	Whether arrow-key focus loops from the last option back to the first (and vice versa). Default: true (same as Combobox). Type boolean Default true
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
required	Marks the control as required for form submission. Type boolean Default false
sideOffset side-offset	Gap between the control and listbox panel in px (default: 6). Type number Default 6
size	Type PkAutocompleteSize Default default
startTypingMessage start-typing-message	Message shown before the user types in async mode. Type string Default Start typing to search…
value	Freeform field value — always mirrors the visible input text. Type string
width	When full, the control stretches to the host width. Type 'full' | undefined
withClear with-clear	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.

Events

Name	Description
change	—
input	—
pk-change	—
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 value button	::part(clear-button)
control	Input control wrapper	::part(control)
empty	Empty-state message	::part(empty)
end	Host end decoration container	::part(end)
input	Autocomplete text input	::part(input)
panel-body	Scrollable listbox region inside the popup panel	::part(panel-body)
start	Host start decoration container	::part(start)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-popup	Positioned suggestion panel host.