Was macht die Komponente?

Die Chip-Komponente ist ein kompaktes UI-Element, das zur Darstellung von ausgewählten Werten innerhalb eines Form-Fieldes dient. Jeder Chip repräsentiert eine Auswahl und kann bei Bedarf wieder entfernt werden.

Wann soll die Komponente eingesetzt werden?

• Wenn Benutzer mehrere Werte aus einer Liste auswählen können.
• Wenn die ausgewählten Werte im Eingabefeld visuell dargestellt werden sollen.
• Wenn eine einfache Möglichkeit zur Entfernung einzelner Einträge erforderlich ist.

Regeln

• Jeder Chip sollte einen klar lesbaren Labeltext enthalten, möglichst kurz und prägnant.
• Bei der Beschriftung ist darauf zu achten, dass sie gut voneinander unterscheidbar sind.

The <sbb-chip-group> component is a container for one or multiple
<sbb-chip> instances.
Generally, it is used in combination with an <sbb-form-field> to allow the
input of multiple string values.

The value property reflects the list of slotted chips. Adding or removing an
<sbb-chip> updates the value property, and vice versa.

<sbb-form-field>
  <label>Field label</label>
  <sbb-chip-group name="field-name">
    <sbb-chip value="Value 1"></sbb-chip>
    ...
    <input />
  </sbb-chip-group>
</sbb-form-field>

The display value of an <sbb-chip> is either its content or the value of the
value property.

By default, when the user presses Enter, the <sbb-chip-group> will create a
new <sbb-chip> and add it to the slotted elements.

Consumers can customize or prevent this behavior by listening to the
chipinputtokenend event.

<!-- Preventing the event will stop the chip-group from converting the input value into a chip -->
<sbb-chip-group name="field-name" @chipinputtokenend="${(event) => event.preventDefault()}">
  ...
  <input />
</sbb-chip-group>

<sbb-chip-group
  name="field-name"
  @chipinputtokenend="${(event) =>
    { 
      event.setValue(transformedValue); 
      event.setLabel('Custom label');
    }
  }"
>
  ...
  <input />
</sbb-chip-group>

Use within forms

The <sbb-chip-group> is a form-associated element that can be part of a form.
Its value is an array of strings.

Note: The name must be set on the <sbb-chip-group>, not on the input

<form>
  <sbb-form-field>
    <sbb-chip-group name="field-name">
      <sbb-chip value="Value 1"></sbb-chip>
      ...
      <input />
    </sbb-chip-group>
  </sbb-form-field>
</form>

Use with Autocomplete

It is possible to combine the functionalities of chip-group and the sbb-autocomplete.

In this scenario, selecting an option will create a new chip using the option value.

<sbb-form-field>
  <sbb-chip-group name="field-name">
    <sbb-chip value="Value 1"></sbb-chip>
    ...
    <input />
  </sbb-chip-group>
  <sbb-autocomplete>
    <sbb-option value="Option A">Option A</sbb-option>
    ...
  </sbb-autocomplete>
</sbb-form-field>

Custom 'separator-keys'

By default, the <sbb-chip-group> creates a new chip on Enter key press.

Consumers can customize the array of keys
that will trigger the chip creation by using the separatorKeys property.

<sbb-chip-group name="field-name" separator-keys="['Enter', 'Space']"> ... </sbb-chip-group>

Add on blur

By default, the <sbb-chip-group> does not create a chip when the input loses focus.

Consumers can enable this behavior by setting the addOnBlur property to true.
When enabled, a chip will be automatically created from the input value when the input loses focus.

<sbb-chip-group add-on-blur> ... </sbb-chip-group>

States

The <sbb-chip-group> has a disabled and a readonly state and reacts to the respective input properties.
The disabled/readonly properties are proxied to the slotted <sbb-chip>s.

<sbb-form-field>
  <sbb-chip-group name="field-name">
    <sbb-chip value="Value 1"></sbb-chip>
    ...
    <input disabled />
    <!-- Or -->
    <input readonly />
  </sbb-chip-group>
</sbb-form-field>

Complex Values

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

To render the complex value, the displayWith function can be used to map
the value to a string represented in the created chips.

Please note that the parameter is the assigned value of the selected option which does not necessarily
align with the type information.

<sbb-form-field>
  <label>Label</label>
  <sbb-chip-group
    name="chip-group-1"
    .displayWith=${(value) => value.property}
    .value=${[{property: 'Option 1', otherProp: 'test'}]}
  >
    <input placeholder="Placeholder" />
  </sbb-chip-group>
  <sbb-autocomplete>
    <sbb-option .value=${{property: 'Option 3', otherProp: 'test'}}>Option 3</sbb-option>
    <sbb-option .value=${{property: 'Option 4', otherProp: 'test'}}>Option 4</sbb-option>
  </sbb-autocomplete>
</sbb-form-field>

Keyboard interaction

At any time, only a single chip (usually, the last one) is focusable and part of the tab order. Users can move between them using the arrow keys.

Style

The <sbb-chip-group> has a negative variant. If within an <sbb-form-field>, the properties automatically sync.

<sbb-form-field negative>
  <sbb-chip-group name="field-name">
    <sbb-chip value="Value 1"></sbb-chip>
    ...
    <input />
  </sbb-chip-group>
</sbb-form-field>

Accessibility

The <sbb-chip-group> follows the grid aria pattern.

API Documentation

class: SbbChipElement, sbb-chip

Properties

Slots

class: SbbChipGroupElement, sbb-chip-group

Properties

Methods

Events

Slots