Combobox (autocomplete)
A text input with a filtered list of suggestions. The server sends a plain <input list> with a <datalist>, which already works in every browser without JavaScript. On init the component promotes it to the ARIA combobox with listbox pattern: consistent rendering, keyboard navigation, accent-insensitive filtering, an empty state and cancelable events. destroy restores the served HTML.
<div class="iv-field" style="max-width: 22rem">
<div class="iv-combobox" data-iv-component="combobox">
<label class="iv-label" for="c-country">Country</label>
<input class="iv-input iv-combobox__input" id="c-country" name="country" type="text" list="c-country-options" autocomplete="off" aria-describedby="c-country-help">
<datalist id="c-country-options">
<option value="Austria"></option>
<option value="Croatia"></option>
<option value="Türkiye"></option>
<option value="Denmark"></option>
<option value="Spain"></option>
<option value="Finland"></option>
<option value="France"></option>
<option value="Germany"></option>
<option value="Ireland"></option>
<option value="Netherlands"></option>
<option value="Portugal"></option>
<option value="Sweden"></option>
</datalist>
</div>
<p class="iv-field__help iv-u-m-0" id="c-country-help">Works as a plain <code><datalist></code> without JavaScript; with JavaScript the suggestions become a filtered listbox.</p>
</div>Strict selection with autoselect
With strict the input only keeps values that exist in the list: free text is reverted on blur and on a second Escape. autoselect highlights the first match so Enter or Tab confirms it.
<div class="iv-field" style="max-width: 22rem">
<div class="iv-combobox" data-iv-component="combobox" data-iv-strict="true" data-iv-autoselect="true" data-iv-min-chars="1">
<label class="iv-label" for="c-language">Documentation language</label>
<input class="iv-input iv-combobox__input" id="c-language" name="language" type="text" list="c-language-options" autocomplete="off" aria-describedby="c-language-help">
<datalist id="c-language-options">
<option value="Catalan"></option>
<option value="Dutch"></option>
<option value="English"></option>
<option value="French"></option>
<option value="German"></option>
<option value="Italian"></option>
<option value="Portuguese"></option>
<option value="Spanish"></option>
</datalist>
</div>
<p class="iv-field__help iv-u-m-0" id="c-language-help">Strict mode: the field only keeps a value from the list, so leaving it with text that matches nothing restores the last valid choice.</p>
</div>// data-iv-component="combobox"
{
strict: true,
autoselect: true,
minChars: 1,
}Options
| Option | Attribute | Default | Effect |
|---|---|---|---|
filter | data-iv-filter | contains | contains or starts; case and accent insensitive. |
minChars | data-iv-min-chars | 0 | Characters typed before the list opens while typing (Down arrow always opens). |
strict | data-iv-strict | false | Revert text that matches no option when focus leaves. |
autoselect | data-iv-autoselect | false | Highlight the first match automatically. |
emptyText | data-iv-empty-text | No matches | Text of the disabled option shown when nothing matches. |
Methods and events
open(), close(), select(valueOrOption), clear(), destroy(), isOpen, value (the confirmed value), optionElements (the listbox rows) and input. Events on the root element: iv:open/iv:close (cancelable) then iv:opened/iv:closed; iv:change (cancelable, detail.value, option, previousValue) then iv:changed when a value is confirmed. The native input also receives synthetic input and change events, so forms and frameworks that listen to them keep working.
Keyboard
Down opens the list and moves the highlight (with wrap-around), Up moves back, Home and End jump, Enter confirms the highlighted option, Escape closes (a second Escape reverts in strict mode), Tab confirms the highlight when autoselect is on and always closes. Typing filters. Focus never leaves the input; the highlighted option is exposed through aria-activedescendant.
Without JavaScript
The native <datalist> provides suggestions. Rendering and keyboard behaviour then depend on the browser, but the field remains usable and the form submits the typed value.
Common mistakes
- Using a combobox for fewer than about six options: a native
<select>is simpler. - Remote or asynchronous data: not supported in v0.2. Render the options on the server.
- Forgetting the visible
<label>; placeholders are not labels.