A combobox is a widget made up of the combination of two distinct elements:
- a single-line textbox
- an associated listbox overlay
Based on the combobox configuration and entered textbox value, options in the listbox will be filtered, checked, focused and the textbox value may be autocompleted. Optionally the combobox contains a graphical button adjacent to the textbox, indicating the availability of the popup.
Fore more information, consult Combobox wai-aria design pattern
Below you will find an overview of all possible
autocomplete behaviors and how they correspond
to the configurable values
- list shows a list on keydown character press
- filter filters list of potential matches according to
- focus automatically focuses closest match (makes it the activedescendant)
- check automatically checks/selects closest match when
selection-follows-focusis enabled (this is the default configuration)
- complete completes the textbox value inline (the 'missing characters' will be added as selected text)
autocomplete="none" is configured, the suggested options in the overlay are not filtered
based on the characters typed in the textbox.
Selection will happen manually by the user.
autocomplete="list" is configured, it will filter listbox suggestions based on textbox value.
autocomplete="inline" is configured, it will present a value completion prediction inside the text input itself.
It does NOT filter list of potential matches.
autocomplete="both" is configured, it combines the filtered list from
'list' with the text input value completion prediction from
This is the default value for
match-mode="begin" is applied, the entered text in the textbox only filters
options whose values begin with the entered text. For instance, the entered text 'ch' will match
with value 'Chard', but not with 'Artichoke'.
match-mode="all" is applied. This will also match parts of a word.
So 'ch' will both match 'Chard' and 'Artichoke'.
When the preconfigurable
match-mode conditions are not sufficient,
one can define a custom matching function.
The example below matches when the Levenshtein distance is below 3 (including some other conditions).
selection-follows-focus will be true (aligned with the
wai-aria examples and the native
It is possible to disable this behavior, so the active/focused and checked/selected values
will be kept track of independently.
Note that, (just like in a listbox), selection-follows-focus will never be applicable for multiselect comboboxes.
rotate-keyboard-navigation will be true (aligned with the
wai-aria examples and the natve
It is possible to disable this behavior, see example below
multiple-choice flag to allow multiple values to be selected.
- keep the listbox overlay open on click of an option
- display a list of selected option representations next to the text box
- make the value of type
Please note that the lion-combobox-selection-display below is not exposed and only serves as an example. The selection part of a multiselect combobox is not yet accessible. Please keep in mind that for now, as a Subclasser, you would have to take care of this part yourself.
All configurations that can be applied to
lion-listbox, can be applied to
lion-combobox as well.
See the listbox documentation for more information.