Autocomplete – digital.sbb.ch

Autocomplete.

Übersicht

Vorschau.

Label

Was macht die Komponente?

Die Komponente schlägt den Nutzenden während der Eingabe passende Optionen vor, basierend auf vorhandenen Daten oder früheren Eingaben. Optionen können gruppiert werden und neben der Option zusätzliche Aktions-Buttons zeigen, zum Beispiel zum Bearbeiten oder Entfernen.

Wann soll die Komponente eingesetzt werden?

Um die Eingabe zu erleichtern und zu beschleunigen, indem mögliche Eingaben vorgeschlagen werden.
Um die Genauigkeit und Konsistenz der eingegebenen Daten zu erhöhen.
Wenn zu einer Option eine Aktion nötig ist, zum Beispiel einen Eintrag aus dem Verlauf zu entfernen.

Regeln.

Bei kleinen Datensätzen ist stattdessen ein Select zu verwenden.
Die Liste zeigt nicht zu viele Vorschläge auf einmal (max. 10).
Nutzende können die Vorschläge ignorieren und eigene Eingaben machen.
Aktions-Buttons gehören zusammen mit der Option in eine Autocomplete-Row. Pro Option sind ein oder mehrere Buttons möglich, nicht alle Optionen brauchen einen.
Die Buttons sind nicht per Tab erreichbar, sondern nur mit den Pfeiltasten (rechts/links). Auf ihre Existenz wird mit einer aria-description an der Option hingewiesen.
In Optionen selbst dürfen keine anderen interaktiven Elemente wie Buttons oder Checkboxen stehen.

Elemente.

Diese Komponente besteht aus einem Hauptelement und seinen Bestandteilen. Die Bestandteile nur innerhalb des jeweiligen Elements verwenden.

sbb-autocomplete

Bestandteile – nur innerhalb von sbb-autocomplete:
- sbb-autocomplete-row
  
  Bestandteile – nur innerhalb von sbb-autocomplete-row:
  - sbb-autocomplete-button

Spezifikation.

In Figma öffnen

Beispiele

Basic.

Negative.

Size S.

Open Above.

Borderless.

Floating Label.

With Error.

Disabled.

Readonly.

Auto Select Active Option.

Require Selection.

No Icon Space.

Scroll.

With Option Group.

Mixed Single Option With Option Group.

With Ellipsis.

With Actions.

HTML in Zwischenablage kopiert.

Implementation

Web Components.

Die Web Component ist im Paket @sbb-esta/lyne-elements enthalten.

Storybook mit Live-Beispielen

Quellcode auf GitHub

Dokumentation.

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.

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 a size property with two sizes available. When slotted in a <sbb-form-field> element, it adapts to the <sbb-form-field> element 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>.

Actions.

An <sbb-option> can be paired with one or more action buttons by wrapping it, together with one or more <sbb-autocomplete-button>, in an <sbb-autocomplete-row>:

<sbb-autocomplete>
  <sbb-autocomplete-row>
    <sbb-option value="Option 1">Option 1</sbb-option>
    <sbb-autocomplete-button icon-name="pen-small"></sbb-autocomplete-button>
  </sbb-autocomplete-row>
  <sbb-option value="Option 2">Option 2</sbb-option>
</sbb-autocomplete>

Options without an associated action can be used as usual, without wrapping them in an <sbb-autocomplete-row>.

Accessibility.

If needed, add an aria-description/ aria-described-by to the <sbb-option> to announce the existence of the action buttons.
This will be read by screen readers when the option is focused.

There is a known issue with NVDA screen reader about keyboard navigation into actions.

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.

Keyboard	Action
`Down Arrow`	Navigate to the next option. Open the panel, if closed.
`Up Arrow`	Navigate to the previous option.
`Right Arrow`	If the active option has one or more action buttons, navigate to the next one. No-op otherwise.
`Left Arrow`	If the active option has one or more action buttons, navigate to the previous one. No-op otherwise.
`Enter`	Select the active option, or activate the focused action button.
`Escape`	Close the autocomplete panel.

`autoSelectActiveOption`.

With autoSelectActiveOption enabled, navigating between options also selects them, without having to press the Enter.
The input and change events emission are postponed to when the panel is closed or on blur.

`autoSelectActiveOptionOnBlur`.

With autoSelectActiveOptionOnBlur enabled, the active option is automatically selected when the input field loses focus.
To prevent accidental selections, this mechanism will not trigger if the input is cleared.

This can be used in combination with autoActiveFirstOption to speed up form completion in copy-paste scenarios.
Be aware that this can lead to unexpected behavior. Carefully test your use case.

`requireSelection`.

Use the requireSelection to clear the input if the user does not explicitly select an option, via mouse click or keyboard selection.

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.

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.

The <sbb-autocomplete-button> has role="button". Since focus is always kept on the input trigger,
buttons can't be reached via Tab, but only with the Left/Right Arrow keys.

Angular.

Diese Komponente gibt es auch für Angular im Paket @sbb-esta/lyne-angular.

Angular-Übersicht

Angular-API

Angular-Beispiele

API

class: `SbbAutocompleteButtonElement`, `sbb-autocomplete-button`.

Properties.

Name	Attribute	Privacy	Type	Default	Description
`disabled`	`disabled`	public	`boolean`	`false`	Whether the component is disabled.
`iconName`	`icon-name`	public	`string`	`''`	The icon name we want to use, choose from the small icon variants from the ui-icons category from here https://icons.app.sbb.ch.
`negative`	`negative`	public	`boolean`	`false`	Negative coloring variant flag.
`optgroup`	-	public	`SbbOptGroupElement \| null`		Gets the parent SbbOptGroupElement, if present.
`option`	-	public	`SbbOptionElement \| null`		Gets the SbbOptionElement on the same row of the button.

Slots.

Name	Description
`icon`	Slot used to display the icon, if one is set

class: `SbbAutocompleteElement`, `sbb-autocomplete`.

Properties.

Name	Attribute	Privacy	Type	Default	Description
`autoActiveFirstOption`	`auto-active-first-option`	public	`boolean`	`false`	Whether the first option is automatically activated when the autocomplete is opened.
`autoSelectActiveOption`	`auto-select-active-option`	public	`boolean`	`false`	Whether the active option should be selected as the user is navigating.
`autoSelectActiveOptionOnBlur`	`auto-select-active-option-on-blur`	public	`boolean`	`false`	When enabled, the active option is automatically selected on blur. This is an experimental feature. It might be subject to changes.
`displayWith`	-	public	`((value: T) => string) \| null`	`null`	Function that maps an option's control value to its display value in the trigger.
`isOpen`	-	public	`boolean`		Whether the element is open.
`negative`	`negative`	public	`boolean`	`false`	Negative coloring variant flag.
`origin`	`origin`	public	`HTMLElement \| null`	`null`	The element where the autocomplete will attach. If not set, as fallback there are two elements which can act as origin with following priority order: 1. `sbb-form-field` if it is an ancestor. 2. trigger element if set. For attribute usage, provide an id reference.
`originElement`	-	public	`HTMLElement \| null`		Returns the element where the autocomplete overlay is attached to.
`position`	`position`	public	`'auto' \| 'above' \| 'below'`	`'auto'`	The position of the autocomplete panel relative to the trigger.
`preserveIconSpace`	`preserve-icon-space`	public	`boolean`	`false`	Whether the icon space is preserved when no icon is set.
`requireSelection`	`require-selection`	public	`boolean`	`false`	Whether the user is required to make a selection when they're interacting with the autocomplete. If the user moves away from the autocomplete without selecting an option from the list, the value will be reset. If the user opens the panel and closes it without interacting or selecting a value, the initial value will be kept.
`size`	`size`	public	`'s' \| 'm' \| null`	`null`	Size variant, either s (lean theme default) or m (standard theme default). When placed inside an `<sbb-form-field>`, the size is inherited from the form field.
`trigger`	`trigger`	public	`HTMLInputElement \| null`	`null`	The input element that will trigger the autocomplete opening. By default, the autocomplete will open on focus, click, input or `ArrowDown` keypress of the 'trigger' element. If not set, will search for the first 'input' child of a 'sbb-form-field' ancestor. For attribute usage, provide an id reference.
`triggerElement`	-	public	`HTMLInputElement \| null`		Returns the trigger element.

Methods.

Name	Privacy	Description	Return	Inherited From
`close`	public	Closes the autocomplete.	`void`	SbbOpenCloseBaseElement
`escapeStrategy`	public	The method which is called on escape key press. Defaults to calling close()	`void`	SbbOpenCloseBaseElement
`open`	public	Opens the autocomplete.	`void`	SbbOpenCloseBaseElement

Events.

Name	Type	Description	Inherited From
`beforeclose`	`Event`	Emits whenever the component begins the closing transition. Can be canceled.	SbbOpenCloseBaseElement
`beforeopen`	`Event`	Emits whenever the component starts the opening transition. Can be canceled.	SbbOpenCloseBaseElement
`change`	`Event`	The change event is fired on the autocomplete's trigger when the user modifies the element's value. Unlike the input event, the change event is not necessarily fired for each alteration to an element's value.	SbbAutocompleteBaseElement
`close`	`Event`	Emits whenever the component is closed.	SbbOpenCloseBaseElement
`input`	`InputEvent`	The input event fires on the autocomplete's trigger when the value has been changed as a direct result of a user action.	SbbAutocompleteBaseElement
`open`	`Event`	Emits whenever the component is opened.	SbbOpenCloseBaseElement

CSS Properties.

Name	Default	Description
`--sbb-autocomplete-z-index`	`var(--sbb-overlay-default-z-index)`	To specify a custom stack order, the `z-index` can be overridden by defining this CSS variable. The default `z-index` of the component is set to `var(--sbb-overlay-default-z-index)` with a value of `1000`.
`--sbb-options-panel-max-height`		Maximum height of the options panel. If the calculated remaining space is smaller, the value gets ignored.
`--sbb-options-panel-offset`	`var(--sbb-spacing-fixed-2x)`	Gap between autocomplete and panel.

Slots.

Name	Description
	Use the unnamed slot to add `sbb-option` or `sbb-optgroup` elements to the `sbb-autocomplete`.

class: `SbbAutocompleteRowElement`, `sbb-autocomplete-row`.

Slots.

Name	Description
	Use the unnamed slot to add a `sbb-option` followed by one or more `sbb-autocomplete-button` elements.

Navigieren auf digital.sbb.ch

Vorschau.

Was macht die Komponente?

Wann soll die Komponente eingesetzt werden?

Ähnliche Komponente.

Regeln.

Elemente.

Spezifikation.

Web Components.

Dokumentation.

In <sbb-form-field>.

Style.

Option highlight.

Option grouping.

Size.

Ellipsis.

Actions.

Accessibility.

Events.

Keyboard interaction.

autoSelectActiveOption.

autoSelectActiveOptionOnBlur.

requireSelection.

Complex Values.

displayWith function.

Accessibility.

Angular.

class: SbbAutocompleteButtonElement, sbb-autocomplete-button.

Properties.

Slots.

class: SbbAutocompleteElement, sbb-autocomplete.

Properties.

Methods.

Events.

CSS Properties.

Slots.

class: SbbAutocompleteRowElement, sbb-autocomplete-row.

Slots.

In `<sbb-form-field>`.

`autoSelectActiveOption`.

`autoSelectActiveOptionOnBlur`.

`requireSelection`.

`displayWith` function.

class: `SbbAutocompleteButtonElement`, `sbb-autocomplete-button`.

class: `SbbAutocompleteElement`, `sbb-autocomplete`.

class: `SbbAutocompleteRowElement`, `sbb-autocomplete-row`.