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.

Child Components

Playground

Examples

The sbb-autocomplete is a component that can be used to display a panel of suggested options connected to a text input.

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>

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.

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.

Properties

Methods

Events

CSS Properties

Slots