# Checkbox-Group

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: ein Element
- Kategorien: Form
- Status: Gestaltungsrichtlinien vollständig

## Links

- Seite auf digital.sbb.ch: https://digital.sbb.ch/de/design-system/lyne/components/checkbox-group/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox-group--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/checkbox-group/overview (API: https://lyne-angular.app.sbb.ch/angular/components/checkbox-group/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=31075-188806
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/checkbox-group

## Elemente

- `sbb-checkbox-group`: It can be used as a container for checkbox elements.

## Übersicht

### Was macht die Komponente?
Die Checkbox-Group fasst [Checkboxen](https://digital.sbb.ch/de/design-system/lyne/components/checkbox/) (auch [Checkbox-Panels](https://digital.sbb.ch/de/design-system/lyne/components/checkbox-panel/) oder [Selection-Expansion-Panels](https://digital.sbb.ch/de/design-system/lyne/components/selection-expansion-panel/)) zu einer Gruppe zusammen. Es können mehrere Einträge gleichzeitig ausgewählt sein. Sie legt Anordnung, Name und Zustände (z.B. Pflichtfeld, deaktiviert) für alle Einträge fest.

### Wann soll die Komponente eingesetzt werden?
* Immer, wenn Checkboxen verwendet werden, die zusammengehören.
* Für eine Einzelauswahl ist stattdessen die [Radio-Button-Group](https://digital.sbb.ch/de/design-system/lyne/components/radio-button-group/) zu verwenden.

### Regeln.
* Eine Checkbox-Group fasst nur Checkboxen zusammen, die zur selben Frage gehören. Die Gruppe braucht eine verständliche Beschriftung, auch für Screenreader (`aria-label`).
* Die Checkboxen stehen bei vielen oder langen Optionen untereinander (`orientation="vertical"`). Nebeneinander nur bei wenigen, kurzen Optionen. Mit `horizontalFrom` lässt sich festlegen, ab welcher Breite sie nebeneinander stehen.
* Alle Checkboxen einer Gruppe haben dieselbe Grösse.
* Ist eine Auswahl erforderlich, wird bei fehlender Auswahl eine Fehlermeldung zur ganzen Gruppe angezeigt.

## Implementation (Web Components, Englisch)

The `<sbb-checkbox-group>` component is used as a container for a collection of either
[sbb-checkbox](https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox--docs)s, [sbb-checkbox-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox-panel--docs)s,
or [sbb-selection-expansion-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-selection-expansion-panel--docs).

```html
<sbb-checkbox-group>
  <sbb-checkbox value="checkbox-1">Label 1</sbb-checkbox>
  <sbb-checkbox value="checkbox-2">Label 2</sbb-checkbox>
  <sbb-checkbox value="checkbox-3">Label 3</sbb-checkbox>
</sbb-checkbox-group>

<sbb-checkbox-group>
  <sbb-selection-expansion-panel>
    <sbb-checkbox-panel>
      Value
      <span slot="suffix">
        <sbb-icon></sbb-icon>
        <span class="sbb-text-xs sbb-text--bold">CHF</span>
        <span class="sbb-text-m sbb-text--bold">40.00</span>
      </span>
    </sbb-checkbox-panel>
  </sbb-selection-expansion-panel>
</sbb-checkbox-group>
```

### Slots

The content is projected in an unnamed slot.

The component can display one or more [sbb-error](https://lyne-elements.app.sbb.ch/?path=/docs/elements-form-field--docs) components
right below the `<sbb-checkbox-group>` using the `error` slot.

```html
<sbb-checkbox-group>
  <sbb-checkbox value="checkbox-1">Label 1</sbb-checkbox>
  <sbb-checkbox value="checkbox-2">Label 2</sbb-checkbox>
  <sbb-checkbox value="checkbox-3">Label 3</sbb-checkbox>
  <sbb-error slot="error">You must accept all the terms and conditions.</sbb-error>
</sbb-checkbox-group>
```

### States

It is possible to mark the entire group as disabled or required using the properties `disabled` and `required`.

```html
<!-- All the child sbb-checkbox will be marked as required. -->
<sbb-checkbox-group required> ... </sbb-checkbox-group>

<!-- All the child sbb-checkbox will be marked as disabled. -->
<sbb-checkbox-group disabled> ... </sbb-checkbox-group>
```

### Style

The `orientation` property is used to set item orientation.
Possible values are `horizontal` (default) and `vertical`.
The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to
indicate the minimum breakpoint from which the orientation changes to `horizontal`.

```html
<sbb-checkbox-group orientation="vertical" horizontal-from="large"> ... </sbb-checkbox-group>
```

The component has a `size` property, which can be used to change the size
of all the inner `<sbb-checkbox>` or `<sbb-checkbox-panel>` elements. Available sizes are `xs`, `s` and `m`.

```html
<sbb-checkbox-group size="s"> ... </sbb-checkbox-group>
```

## API (Web Components, Englisch)

Vollständige API-Tabellen (Attribute, Events, Slots, CSS-Eigenschaften): https://digital.sbb.ch/de/design-system/lyne/components/checkbox-group/api.md