What does the component do?

The component offers suggestions to the user during input, based on existing data or previous input, to make input easier and faster.

When should the component be used?

• To improve the data input experience by suggesting possible/allowed inputs.
• To increase the accuracy and consistency of the data input.
• To reduce the time users need to fill in forms.

Rules

• The component should not be used for small data sets (e.g. only 10 entries/options).
• The autocomplete list should not display too many suggestions at once in order to maintain clarity (max. 10 suggestions).
• Users should be able to ignore the autocomplete function and make their own entries.

Playground

The sbb-autocomplete is a component that can be used to display a panel of suggested options connected to a text input.
Use it when you need a basic autocomplete: a panel with a list of selectable and possibly grouped options.
If you need buttons connected to the options, use the sbb-autocomplete-grid.

It's possible to set the element to which the component's panel will be attached using the origin prop,
and the input which will work as a trigger using the trigger prop.
Both accept an id or an element reference.

<!-- Origin element -->
<div id="autocomplete-origin">Another origin</div>

<!-- Trigger element -->
<input id="autocomplete-txt" placeholder="Another trigger element" />

<sbb-autocomplete origin="autocomplete-origin" trigger="autocomplete-txt">
  <sbb-option value="Option A">Option A</sbb-option>
  <sbb-option value="Option B">Option B</sbb-option>
  <sbb-option value="Option C">Option C</sbb-option>
</sbb-autocomplete>

In sbb-form-field

If the component is used within a sbb-form-field,
it will automatically connect to the native <input> as trigger and will display the option panel above or below the sbb-form-field.

<!-- Origin element -->
<sbb-form-field>
  <label>Label</label>
  <!-- Trigger element -->
  <input placeholder="Trigger element" />

  <sbb-autocomplete>
    <sbb-option icon-name="clock-small" value="Option 1"> Option 1 </sbb-option>
    <sbb-option icon-name="clock-small" value="Option 2"> Option 2 </sbb-option>
    <sbb-option icon-name="clock-small" value="Option 3"> Option 3 </sbb-option>
  </sbb-autocomplete>
</sbb-form-field>

Style

Option highlight

By default, the autocomplete will highlight the label of the sbb-option in the panel, if it matches the typed text.
See the sbb-option for more details.

Option grouping

The displayed sbb-option can be collected into groups using sbb-optgroup element:

<!-- Origin element -->
<sbb-form-field>
  <label>Label</label>
  <!-- Trigger element -->
  <input placeholder="Trigger element" />

  <sbb-autocomplete>
    <sbb-optgroup label="Group 1">
      <sbb-option icon-name="clock-small" value="Option 1"> Option 1 </sbb-option>
      ...
    </sbb-optgroup>
    <sbb-optgroup label="Group 2"> ... </sbb-optgroup>
  </sbb-autocomplete>
</sbb-form-field>

Size

The component has no size property but, when slotted in a sbb-form-field, it adapts to the parent size.

<sbb-form-field size="s">
  <label>Label</label>
  <input placeholder="Trigger element" />
  <sbb-autocomplete> ... </sbb-autocomplete>
</sbb-form-field>

Ellipsis

It's possible to truncate the label (apply ellipsis) of slotted sbb-option elements with the sbb-options-nowrap CSS class.
To select which elements should be affected, the consumer can set the class on either the html tag, the sbb-autocomplete, or the single sbb-option.

Events

The sbb-option emits the optionSelected event when selected via user interaction.

Keyboard interaction

The options panel opens on focus, click or input events on the trigger element, or on ArrowDown keypress;
it can be closed on backdrop click, or using the Escape or Tab keys.

Setting the autoSelectActiveOption property to true allows users
to automatically select the option reached via keyboard navigation as the input value,
without having to press the Enter key to confirm.

On the other hand, it's possible to use the requireSelection to clear the input
if the user does not explicitly select a value, via mouse click or keyboard selection.

Accessibility

The sbb-autocomplete implements the ARIA combobox interaction pattern.

The text input trigger specifies role="combobox" while the content of the pop-up applies role="listbox".
Because of this listbox pattern, you should not put other interactive controls, such as buttons or checkboxes, inside an autocomplete option.
Nesting interactive controls like this interferes with many assistive technologies.

The component preserves focus on the input trigger,
using aria-activedescendant to support navigation though the autocomplete options.

Complex Values

This component supports any types of values, including complex objects.
The type can be specified using the generic type parameter T of SbbAutocomplete<T> and SbbOption<T>.

const values = [
  { value: 'value 1', name: 'Option 1' },
  { value: 'value 2', name: 'Option 2' },
];

<sbb-form-field>
  <input />
  <sbb-autocomplete .displayWith="${(value) => value.name}">
    <sbb-option .value="${values[0]}">Option 1</sbb-option>
    <sbb-option .value="${values[1]}">Option 2</sbb-option>
  </sbb-autocomplete>
</sbb-form-field>

displayWith function

When using complex values, the selection should most likely still be represented as text.
To achieve this, you can use the displayWith property which accepts a function.
This function receives the selected value and should return a string.

Please note that the parameter is the assigned value of the selected option which does not necessarily
align with the type information.

Properties

Methods

Events

CSS Properties

Slots