Combobox

A filterable single-select combobox whose input is the control: an always-visible editable input shows the selected label, typing filters options in real time, and value takes option.value on selection.

Positioning vs. Select and AutoComplete

• Select: button-triggered dropdown, the value is limited to options, no always-visible input;
• AutoComplete: free-text suggestion, the value can be any typed content (not necessarily from options);
• Combobox: the input is the control, typing is only for filtering, the value must come from an option (option.value).

Basic Usage

Basic usage

Example

Click/focus to open the dropdown; typing filters in real time (filterable is enabled by default, substring-matching the label); ↑/↓ move the highlight, Enter selects, Esc closes.

Preset Value (controlled)

Preset value (controlled)

Example

value is a controlled property: it is written back after selection; externally changing the property also immediately reflects in the input's label.

Externally Controlled Value

External controlled value

Set to AppleClear value

Example

In controlled mode, the host can drive the component display via the value attribute at any time:

Filtering & Blur Boundaries

Input filtering + blur fallback

Example

If you type without selecting and then blur/press Esc, the input falls back to the currently selected label (non-destructive by default — the selected value is not lost).

Not Filterable

Filtering disabled (filterable="false")

Example

With filterable="false", typing no longer filters options; select only via keyboard ↑/↓ + Enter or mouse.

Clearable

Clearable

Example

When a value is selected, a clear button appears; clicking clears value and dispatches oas-clear and oas-change.

Loading

Loading

Example

While loading, the dropdown shows a "加载中…" placeholder (the host sets it during remote data requests).

Empty State

No options (empty)

Example

When options are empty, the dropdown shows "暂无选项"; when filtering yields no match, "无匹配选项" is shown.

Disabled

Disabled

Example

Events

Event output

Example

Listen to oas-input (filter keyword), oas-change (selection), oas-clear (clear):

API

Attributes

Attribute	Description	Type	Default
clearable	Clearable (shows a clear button when a value exists; clearing dispatches oas-clear)	boolean	—
disabled	Disabled (no input, no dropdown)	boolean	—
filterable	Filter labels in real time while typing (filterable="false" disables local filtering)	string	true
loading	Loading placeholder (dropdown shows "加载中…")	boolean	—
options	Options, JSON array [{ label, value, disabled? }]	Option[] | string	[]
placeholder	Placeholder text	—	—
value	Current value (controlled, the selected option's option.value)	string	—

Events

Event	Description
oas-change	Selection/clear change, detail: { value }
oas-clear	Clear button clicked, detail: { value } (value before clearing)
oas-input	Filter keyword typed, detail: { value }

Keyboard: Enter / focus to open, ↑/↓ to move the highlight, Enter to select, Esc to close and revert.