AutoComplete

Type to get suggestions: the value is free text (browser address bar / datalist mental model) — the suggestion list only aids input. Keyboard selection, grouping, debounced remote suggestions, and custom rendering are supported.

Boundary vs. Select(searchable) / Combobox

Component	Value source	Input form	Best for
oas-auto-complete	Any free text; suggestions are shortcuts	Input is the control	Search-box suggestions, email completion, free-form tags
oas-select searchable	Must come from the option set	Button-triggered; search box appears when expanded	Constrained choice (value must be valid)
oas-combobox	Must come from the option set	Input is the control; typing only filters	Always-visible-input constrained single select

When the value must be one of the options, use select(searchable) or combobox instead of trying to add "strict validation" to auto-complete; for multiple/tags scenarios use oas-select multiple or oas-dynamic-tags — auto-complete stays single-value free text.

Basic Usage

Basic usage

Example

Typing auto-filters matching items in the dropdown; the first item is highlighted by default and Enter commits it directly; ↑/↓ move the highlight, Esc closes; blur does not clear the input (free text never falls back).

Preset Value

Preset value

Example

Reading/writing the current value goes through the public value property (el.value to read, el.value = x to write, matching native input.value). Note the label / value split: this component's submission semantics are the visible text — after selecting a suggestion, el.value returns that suggestion's label (visible text), while the value attribute is the option.value (e.g. apple); oas-form's values snapshot reads the attribute (= option.value). The two are different layers — pick per need.

Clearable

Clearable

Example

A clear button appears when the input has content; clicking clears the input and dispatches oas-clear and oas-change (empty value).

Remote Suggestions (debounce + loading)

Remote search suggestions

Example

debounce (ms, default 0 = off) only debounces oas-input dispatching and filtering — the input display is never debounced; the host sets loading while requesting, the dropdown shows a loading placeholder, and refilling options renders the suggestions.

Show on Focus (trigger-on-focus)

Show all suggestions on focus (trigger-on-focus)

Example

Off by default (popping the full list on focusing an empty input disturbs compact forms); enabling it follows the datalist mental model: focus shows suggestions filtered by the current input.

Grouped Suggestions

Groups (group)

Example

Options with a group field render group titles (not selectable) with indented options; ↑/↓ navigate continuously across groups.

Large Datasets (virtual scrolling)

Virtual scrolling (1000 suggestions)

Example

With virtual, the suggestion panel renders only the visible window (reusing oas-virtual-list window math with top/bottom padding holding the scroll height) — thousands of suggestions scroll smoothly and the panel height stays constant; item-height tunes the fixed row height (default 36). While navigating with ↑/↓ the window follows the highlighted item and aria-activedescendant keeps pointing at a visible row; options with group automatically fall back to full rendering (same contract as oas-select).

Custom Option Rendering

Custom option (oas-option-render event)

Example

Custom option (template slot)

Example

The dual channel matches oas-select: listen to oas-option-render (detail.element is the text container the host can rewrite into icons/rich text); or provide a static skeleton via <template slot="option"> whose [data-option-label] node auto-binds the option text.

Panel Slots (header / footer / empty)

Panel header/footer and empty slots

Hint: try a fruit nameView all fruits →Try another keyword

Example

header / footer slots render at the top/bottom of the suggestion panel (hint bar, "view all" link); the empty slot replaces the default "no match" text.

Size & Status

Sizes (size)

Example

Status (status)

Example

size supports small / medium / large (follows the nearest oas-config-provider size injection); status supports success / warning / error (error syncs aria-invalid, drivable by oas-form-item validation).

Variant

Variant (variant)

Example

variant aligns with the three oas-input variants: outlined (default) / filled (gray fill, border on hover) / borderless (no border, no focus shadow); invalid values fall back to outlined.

Focus Events (oas-focus / oas-blur)

focus / blur events

Example

Focus/blur dispatch oas-focus / oas-blur with detail: { value } carrying the current input text, matching the oas-input event contract.

Readonly

Readonly

Example

readonly allows focus & copy but no editing; focus and keyboard no longer open suggestions.

IME (Input Method Editor)

During IME composition (before confirming the candidate) the component does not filter, does not dispatch oas-input, and Enter never mis-selects a suggestion; after composition ends, one filtered update fires with the final text. Try typing Chinese in any demo on this page — no extra configuration needed.

Disabled

Disabled

Example

No Match

Empty state

Example

Events

Input & selection events

Example

Listen to oas-input (typing, after debounce), oas-change (select or clear), oas-clear (clear):

required

required (native validation chain)

Example

required drives the native validation chain (form-associated): when unfilled, checkValidity() returns false (valueMissing) and native form submission is blocked; it recovers to :valid once filled.

Programmatic read/write of the current value goes through the public value property (like the native input.value): el.value reads the current input text; el.value = x writes the controlled value attribute and immediately syncs the inner control (clearing the in-progress filter query) without dispatching events.

Panel placement

placement controls the suggestion panel placement in 12 directions (aligned with the floating-positioning engine; -start / -end are logical writing-direction semantics, mirrored automatically in RTL): flips along the main axis when space is short and avoids viewport edges. Default bottom-start (panel's start edge aligned with the input's start edge, opening downward); the actual placement (including flips) is written to the panel's data-placement.

placement=top-start (opens upward)

Example

autofocus

autofocus is forwarded to the inner input (native autofocus doesn't pierce Shadow DOM): the component focuses once after mounting. Click the button below to mount a fresh autofocus instance and watch the caret land inside the input.

Focused on mount

Mount an autofocus input

Example

API

oas-auto-complete

Attributes

Attribute	Description	Type	Default
autofocus	Focuses the inner input after mounting	boolean	—
clearable	Clearable (shows a clear button when the input has content; clearing dispatches oas-clear and an empty oas-change)	boolean	—
debounce	Input debounce (ms, default 0 = off): only debounces oas-input dispatch and filtering, never the input display	string	0
disabled	Disabled	boolean	—
item-height	Fixed virtual row height in px (with virtual, default 36)	string	36
loading	Loading placeholder (dropdown shows a loading state; remote-suggestion request state)	boolean	—
options	Options, JSON array [{ label, value, disabled?, group? }] (group is the group title)	Option[] | string	[]
placeholder	Placeholder text	string	—
placement	12-direction panel placement (engine flip/RTL result written to data-placement)	string	bottom-start
readonly	Readonly (focusable & copyable, not editable; focus and keyboard never open suggestions)	boolean	—
required	Required marker (drives the native valueMissing validation chain; not passed through to the inner control)	boolean	—
size	Size tier: small / medium / large (default medium, follows the nearest config-provider injection)	string	medium
status	Validation status: success / warning / error (error syncs aria-invalid, drivable by oas-form-item validation)	string	—
trigger-on-focus	Show suggestions on focus (datalist mental model; off by default — input-first)	boolean	—
value	Preset value	string	—
variant	Visual variant: outlined (default) / filled / borderless; invalid values fall back silently	string	—
virtual	Virtual scrolling (renders only the visible window via oas-virtual-list; grouped options fall back to full rendering)	boolean	—

Property (JS property; see each row for attribute reflection)

Property	Description	Type	Default
value	Current value: the visible text (the selected suggestion label after choosing); the value attribute is the option.value	string	—

Events

Event	Description
oas-blur	Dispatched on blur with the current input text, detail: { value: this.input?.value ?? '' }
oas-change	Selected or cleared, detail: { value, label }
oas-clear	Clear button clicked, detail: { value } (value before clearing)
oas-focus	Dispatched on focus with the current input text, detail: { value: this.input?.value ?? '' }
oas-input	While typing (after debounce), detail: { value }
oas-option-render	Dispatched after each option row renders, detail: { index, option, element }; the host can rewrite element (icons/rich text)

Slots

Name	Description
empty	Custom no-match empty state (replaces the default text)
footer	Suggestion panel footer content (e.g. a view-all link)
header	Suggestion panel header content (e.g. a hint bar)
template[slot="option"]	Custom option template skeleton; the [data-option-label] node auto-binds the option text

CSS Variables

CSS Variable	Default
--oas-auto-complete-dropdown-height	240px
--oas-glass-blur	none
--oas-glass-ring	transparent

Keyboard: ↑/↓ to move (looping), Enter to select the highlighted item (first item highlighted by default), Esc to close.