What does the component do?

The chip component is a compact UI element that is used to display selected values within a form field. Each chip represents a selection and can be removed again if required.

When should the component be used?

• When users can select multiple values from a list.
• If the selected values are to be displayed visually in the input field.
• When an easy way to remove individual entries is required.

Rules

• Each chip should contain a clearly legible label text, as short and concise as possible.
• When labelling, make sure that they are easily distinguishable from each other.

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