What does the component do?

The component offers the same functionalities as the Autocomplete component, but also offers the option of displaying buttons next to the options.

When should the component be used?

• Only if buttons are required in addition to the options shown in the autocomplete list.

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-grid is a component that can be used to display a panel of suggested options connected to a text input,
with each option connected to one or more buttons.
Use it when you need an autocomplete in which every selectable option in the panel needs one or more related button.
If you don't need actions, use the sbb-autocomplete.

The component is strictly connected to:

• the sbb-autocomplete-grid-row, which is a wrapper for both option and buttons;
• the sbb-autocomplete-grid-option, which displays a selectable option within a panel;
• the sbb-autocomplete-grid-cell, which is a wrapper a for button element;
• the sbb-autocomplete-grid-button, which displays a button within a row;
• the sbb-autocomplete-grid-optgroup, which can be used to group more row within a group.

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-grid origin="autocomplete-origin" trigger="autocomplete-txt">
  <sbb-autocomplete-grid-row>
    <sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
    <sbb-autocomplete-grid-cell>
      <sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
    </sbb-autocomplete-grid-cell>
  </sbb-autocomplete-grid-row>
  <sbb-autocomplete-grid-row>
    <sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
    <sbb-autocomplete-grid-cell>
      <sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
    </sbb-autocomplete-grid-cell>
  </sbb-autocomplete-grid-row>
</sbb-autocomplete-grid>

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">
  <!-- Trigger element -->
  <input placeholder="Trigger element" />

  <sbb-autocomplete-grid>
    <sbb-autocomplete-grid-row>
      <sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
      <sbb-autocomplete-grid-cell>
        <sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
      </sbb-autocomplete-grid-cell>
    </sbb-autocomplete-grid-row>
    <sbb-autocomplete-grid-row>
      <sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
      <sbb-autocomplete-grid-cell>
        <sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
      </sbb-autocomplete-grid-cell>
    </sbb-autocomplete-grid-row>
  </sbb-autocomplete-grid>
</sbb-form-field>

Style

Option highlight

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

Option grouping

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

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

  <sbb-autocomplete-grid>
    <sbb-autocomplete-grid-optgroup>
      <sbb-autocomplete-grid-row>
        <sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
        <sbb-autocomplete-grid-cell>
          <sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
        </sbb-autocomplete-grid-cell>
      </sbb-autocomplete-grid-row>
      ...
    </sbb-autocomplete-grid-optgroup>
    <sbb-autocomplete-grid-optgroup>
      <sbb-autocomplete-grid-row>
        <sbb-autocomplete-grid-option value="100">Option 100</sbb-autocomplete-grid-option>
        <sbb-autocomplete-grid-cell>
          <sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
        </sbb-autocomplete-grid-cell>
      </sbb-autocomplete-grid-row>
      ...
    </sbb-autocomplete-grid-optgroup>
  </sbb-autocomplete-grid>
</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-grid> ... </sbb-autocomplete-grid>
</sbb-form-field>

Events

The sbb-autocomplete-grid-option emits the autocompleteoptionselected 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-grid implements the ARIA combobox-grid interaction pattern.

The text input trigger specifies role="combobox" while the content of the pop-up applies role="grid".
The inner option and actions have role="gridcell", while the buttons inside the action have role="button".
Note that since the focus must always be on the connected input, those buttons can't be reached via Tab,
but only with arrow navigation; note also that when a button is reached, going up or down will move to the previous/next option
and not to the previous/next button.

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 SbbAutocompleteGrid<T> and SbbAutocompleteGridOption<T>.

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

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

CSS Properties

Slots