Combobox

size

Field size, matching aihio-input.

Attributes

value

string

Value of the initially chosen option, and the value a form reset returns to. The value property carries the live choice.

name

string

Form field name. The chosen option's value (not its label) is submitted under it. Without it the field submits nothing.

form

string

Id of an external form that owns the field.

placeholder

string

Placeholder text. It is not a label.

disabled

boolean default false

Disables the field. A disabled field submits nothing.

readonly

boolean default false

Shows the chosen option without letting it change. The value still submits.

required

boolean default false

Requires a choice for native constraint validation.

error

boolean default false

Shows error styling and sets aria-invalid. aihio-field sets this from its error slot.

size

one of smmdlg default md

Field size, matching aihio-input.

filter

one of containsstarts-withnone default contains

How typing filters the options. contains ranks prefix matches first, then word-start matches, then any match. none shows every option as given, for lists filtered by a server.

allow-custom

boolean default false

Accepts typed text that matches no option; the text becomes the value. Without it, leaving the field reverts unmatched text to the chosen option.

loading

boolean default false

Shows a loading row and marks the list busy while options are being fetched.

empty-text

string default No results

Shown and announced when no option matches.

loading-text

string default Loading…

Shown and announced while loading is set.

results-text

string

Result-count announcement with a {count} placeholder, for localisation (e.g. "{count} tulosta"). Defaults to "1 result" / "N results".

open

boolean default false

Reflects whether the list is showing. Set or remove it to open or close the list.

Properties

value

string

Get or set the chosen option's value (or the free text, with allow-custom). Setting it does not fire aihio-change.

defaultValue

string

Get or set the reset value reflected by the value attribute

selectedOption

HTMLElement | null read-only

The chosen aihio-option, or null

control

HTMLInputElement | null read-only

The native text input carrying role="combobox"

form

HTMLFormElement | null read-only

The owning form, or null outside one

validity

ValidityState | null read-only

Native constraint validation state

validationMessage

string read-only

Native validation message

willValidate

boolean read-only

Whether the field participates in constraint validation

Methods

open(): void

Opens the list showing every option, with the chosen one highlighted.

close(): void

Closes the list, reverting unconfirmed text to the chosen option.

toggle(): void

Opens or closes the list.

focus(options?: FocusOptions): void

Moves focus to the text input.

checkValidity(): boolean

Runs native constraint validation and returns whether the field is valid.

reportValidity(): boolean

Runs native constraint validation and shows the browser message if invalid.

setCustomValidity(message: string): void

Sets a custom validation message.

Events

aihio-change

detail { value: string, label: string }

Fired when the person commits a different choice, or when a form reset changes it. Not fired for programmatic value changes.

aihio-search

detail { query: string }

Fired on every keystroke with the typed text. Use it to fetch options for filter="none".

aihio-open

Fired after the list opens.

aihio-close

detail { reason: string }

Fired after the list closes.

Composition

Allowed children

aihio-option

Your obligations

• error When the combobox is not inside an aihio-field

  Label it with aria-labelledby pointing at visible text, or aria-label. Placeholder is not a label, and a wrapping <label> would fold the option text into the field's name.

  Checked as combobox-label

• error When two aihio-option children share a value

  Give every option a distinct value; the value is how the chosen option is found again.

  Checked as combobox-option-values

• warn When the combobox is inside a <form> and its value should be submitted

  Set name. A combobox without a name is omitted from FormData.

  Checked as combobox-form-name

Handled for you

• A real <input role="combobox"> with aria-autocomplete="list", aria-expanded, and aria-controls pointing at the listbox
• DOM focus stays in the input; aria-activedescendant follows the highlighted option, in the same tree as the options it names
• Options render as role="option" inside role="listbox"; the chosen option has aria-selected="true" and a check mark, disabled options have aria-disabled
• ArrowDown/ArrowUp open the list and move through enabled options (wrapping); Alt+ArrowDown opens without moving; Alt+ArrowUp accepts and closes; PageDown/PageUp jump ten
• Enter chooses the highlighted option; Escape closes and reverts unconfirmed text, and is left alone when the list is closed so a surrounding dialog still closes
• Tab accepts the highlighted option and moves on; leaving the field any other way keeps the previous choice unless the text matches an option exactly
• Typing filters case- and accent-insensitively ("aland" finds "Åland"), ranks prefix matches first, highlights the first match, and sets the matched text in bold
• A polite status region announces the result count, the empty message, or the loading message once typing pauses
• The toggle button is out of the tab order, carries the field's label, and exposes aria-expanded
• Keys pressed while an IME is composing are left to the IME
• The chosen value submits through a hidden input under name; required, form reset, <fieldset disabled>, and the form attribute behave natively
• The list renders in the top layer, flips above the field when there is more room there, and fits the visual viewport above an on-screen keyboard
• Forced colours restate the highlighted and disabled states with system colours; reduced motion removes the open animation and spinner