Was macht die Komponente?

Die Komponente bietet den Nutzenden während der Eingabe Vorschläge an, basierend auf bereits vorhandenen Daten oder vorherigen Eingaben, um die Eingabe zu erleichtern und zu beschleunigen.

Wann soll die Komponente eingesetzt werden?

• Um die Experience bei der Eingabe von Daten zu verbessern, indem mögliche/erlaubte Eingaben vorgeschlagen werden.
• Um die Genauigkeit und Konsistenz der eingegebenen Daten zu erhöhen.
• Um die Zeit zu reduzieren, welche die Nutzenden für das Ausfüllen von Formularen benötigen.

Regeln

• Die Komponente soll nicht bei kleinen Datensätzen (z.b. nur 10 Einträge/Optionen) verwendet werden.
• Die Autocomplete-Liste soll nicht zu viele Vorschläge auf einmal anzeigen, um die Übersichtlichkeit zu bewahren (max. 10 Vorschläge).
• Die Nutzenden sollen die Möglichkeit haben, die Autocomplete-Funktion zu ignorieren und eigene Eingaben zu machen.

Spielwiese

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