What does the component do?

A select allows users to make a choice from a list of several options.

When should the component be used?

• When users should make a selection from an extensive list of options.
• To save space on the user interface by hiding the options in a drop-down menu.
• When the number of choices is too large for radio buttons or checkboxes.

Rules

• The options in the select menu should be clearly labelled and easy to understand.
• Use a useful default selection if this is relevant for the use case.

Playground

The sbb-select is a component which provides a list of selectable options in an overlay panel,
emulating the behaviour of a native <select>.

In sbb-form-field

If the component is used within a sbb-form-field, it will automatically display the option panel above or below it;
otherwise, the panel takes the component's parent element as origin.
Options or groups of options (see sbb-option /
sbb-option-group components)
can be provided via an unnamed slot.

<sbb-form-field>
  <label>Train types</label>
  <sbb-select>
    <sbb-option value="Astoro" selected>Astoro</sbb-option>
    <sbb-option value="Flirt">Flirt</sbb-option>
    <sbb-option value="Domino">Domino</sbb-option>
  </sbb-select>
</sbb-form-field>

The component has a value property, which can be a string or a string array (when multiple is set to true).
If no value has been set, it is possible to display a placeholder using the placeholder property.

Also note that if the value is set on the sbb-select, it will override all the selected attributes on the internal sbb-options,
so setting a default value should be done using the value attribute on the sbb-select and not by setting the
selected attribute on the internal sbb-options.

States

It is possible to display the component in disabled or readonly state by using the self-named properties. The component
has a required property, which can be useful for setting a custom sbb-error message within a sbb-form-field.

<sbb-form-field>
  <label>Pick one:</label>
  <sbb-select placeholder="1st gen starters">
    <sbb-option value="Bulbasaur">Bulbasaur</sbb-option>
    <sbb-option value="Charmander">Charmander</sbb-option>
    <sbb-option value="Squirtle">Squirtle</sbb-option>
  </sbb-select>
  <sbb-error>You must pick one!</sbb-error>
</sbb-form-field>

Multiple

If the multiple property is set to false, only one option can be selected:
in this case the placeholder will be replaced by the chosen value and a check mark will appear
on the right of the selected option in the panel.

If the multiple attribute is set to true, a visual checkbox will appear on the left of any option in the panel, and
the selected values will be displayed in selection order, separated by a comma.

<sbb-form-field>
  <label>Cities</label>
  <sbb-select multiple>
    <sbb-optgroup label="Switzerland">
      <sbb-option value="Zurich">Zurich</sbb-option>
      <sbb-option value="Bern">Bern</sbb-option>
      <sbb-option value="Lugano">Lugano</sbb-option>
    </sbb-optgroup>
    <sbb-optgroup label="Italy">
      <sbb-option value="Rome">Rome</sbb-option>
      <sbb-option value="Milan">Milan</sbb-option>
    </sbb-optgroup>
  </sbb-select>
</sbb-form-field>

Style

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>Train types</label>
  <sbb-select>...</sbb-select>
</sbb-form-field>

Events

Consumers can listen to the native change/input event on the sbb-select component to intercept the selection's change;
the current value can be read from event.target.value.
Additionally sbb-option will emit optionSelected when selected via user interaction.

Accessibility

The select follows the combobox pattern. As a technical difficulty, we have to copy the combobox element into the light DOM.
As a consequence, linking labels is not fully supported. While aria-label, aria-labelledby and aria-describedby on the sbb-select work,
using <label> together with sbb-select is only partially supported.
As workaround, we copy the text into the aria-label of the combobox element, but this remains not synchronized.
Whenever a <label> gets a change, we won't be able to detect it, and we won't be able to update the aria-label.
The only two exceptions are when connectedCallback() gets called and when the document language changes.

Fully supported:

<sbb-select aria-label="Select train type">...</sbb-select>

Changes to the <label>-text might not be reflected after initialization:

<sbb-form-field size="s">
  <label>Train types</label>
  <sbb-select>...</sbb-select>
</sbb-form-field>

Keyboard interaction

Closed panel, sbb-select has focus:

Opened panel:

Complex Values

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

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

For types other than string, the value must be set via property.

<sbb-select .value="${values[0]}" name="name">
  <sbb-option .value="${values[0]}">Option 1</sbb-option>
  <sbb-option .value="${values[1]}">Option 2</sbb-option>
</sbb-select>

Properties

Methods

Events

CSS Properties

Slots