Lion Logo Lion Guides Components Docs Blog Toggle darkmode

Combobox: Features

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

Autocomplete

Below you will find an overview of all possible autocomplete behaviors and how they correspond to the configurable values none, list, inline and both.

listfilterfocuscheckcomplete
none
list
inline
both
  • list shows a list on keydown character press
  • filter filters list of potential matches according to matchmode or provided matchCondition
  • focus automatically focuses closest match (makes it the activedescendant)
  • check automatically checks/selects closest match when selection-follows-focus is enabled (this is the default configuration)
  • complete completes the textbox value inline (the 'missing characters' will be added as selected text)

When 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.

When autocomplete="list" is configured, it will filter listbox suggestions based on textbox value.

When autocomplete="inline" is configured, it will present a value completion prediction inside the text input itself. It does NOT filter list of potential matches.

When autocomplete="both" is configured, it combines the filtered list from 'list' with the text input value completion prediction from 'inline'. This is the default value for autocomplete.

Match Mode

When 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'. By default 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).

Options

Changing defaults

By default selection-follows-focus will be true (aligned with the wai-aria examples and the native <datalist>). 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.

By default rotate-keyboard-navigation will be true (aligned with the wai-aria examples and the natve <datalist>). It is possible to disable this behavior, see example below

Multiple choice

Add multiple-choice flag to allow multiple values to be selected. This will:

  • 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 Array instead of String

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.

Invoker button

Listbox compatibility

All configurations that can be applied to lion-listbox, can be applied to lion-combobox as well. See the listbox documentation for more information.