Combobox

An accessible combobox over a native input and list.

The server answers each query with the matching countries.

Open in new tab

Each preview is its own Live page in a frame, because this site is a Vue 3.5 app built on the Pulsar starter kit. An open list or popover stays inside its frame; in your application it opens over the page.

Installation

bash
suprnova live:add combobox

Usage

html
{% import "suprnova-ui/combobox/combobox.html" as combobox %}
{% call combobox::combobox("country", "Country", countries, query=country_query, placeholder="Type a country", value=country) %}{% endcall %}

Examples

Browser filtering

With `remote=false` the element filters a fixed list in the browser.

Open in new tab

Keyboard and accessibility

suprnova.combobox - the accessible combobox pattern over a native input and list (FORM-008). Before the script loads, a datalist gives the same options natively, so the control works with the helper absent. sn-combobox (combobox.js) takes over the listbox: it sets aria-expanded, moves aria-activedescendant with the arrow keys, selects on Enter or click, and closes on Escape.

Two fields carry the state. The field `name` is the selected option's value: a hidden input bound to it, which a selection fills with the option's first element and editing the text clears. The text input is bound to `<name>_query`, what the user typed, the query a remote listbox answers; a selection writes the option's label there. Both render the island's current values (FORM-009): `value` fills the hidden input, whose option the script marks selected when it connects (the listbox is hidden until then), and `query` fills the text. Without the script the datalist offers the labels as text, so the query field carries the choice and the value stays empty.

By default the options are the server's answer to the query (remote): the listbox carries data-sn-remote and data-sn-query, the query the server rendered it for. The element shows every option while that query is the input's current text, whatever the server matched (FORM-012), and keeps a listbox rendered for older text hidden, so a stale result never replaces results for a newer query (stale suppression, FORM-008, in the script's acceptsResults). The component re-renders the options for the query on every render, a model update included. With remote=false the options are a fixed list and the element filters them by the typed text.

The wrapper is keyed with live:preserve.self, so its upgrade marker survives a morph; the script re-applies its input changes after a re-render. Classification: varies with the island.

API reference

combobox

ParameterDefaultDescription
nameRequiredThe model field that carries the chosen option's value; the typed text binds to `<name>_query`.
labelRequiredThe visible label.
optionsRequired`(value, label)` pairs: the server's answer to the query, or a fixed list.
queryRequiredThe island's current `<name>_query` text, so the input shows it.
placeholderRequiredPlaceholder text.
remotetrue`true` when the server answers each query; `false` to filter a fixed list in the browser.
value""The island's chosen value, so the script marks that option selected.