# Checkbox

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/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/checkbox/overview (API: https://lyne-angular.app.sbb.ch/angular/components/checkbox/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-20
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/checkbox

## Elemente

- `sbb-checkbox`: It displays a checkbox enhanced with the SBB Design.

## Verwandte Komponenten

- Ähnlich: [Checkbox-Panel](https://digital.sbb.ch/de/design-system/lyne/components/checkbox-panel/index.md), [Radio-Button](https://digital.sbb.ch/de/design-system/lyne/components/radio-button/index.md), [Toggle-Check](https://digital.sbb.ch/de/design-system/lyne/components/toggle-check/index.md)

## Übersicht

### Was macht die Komponente?
Eine Checkbox ist ein Auswahlfeld. Nutzende wählen damit eine oder mehrere Optionen aus oder ab.

### Wann soll die Komponente eingesetzt werden?
* Um mehrere unabhängige Optionen auszuwählen.
* Um eine Ja/Nein-Auswahl anzubieten, zum Beispiel eine Zustimmung wie die Newsletter-Anmeldung.
* Um eine Gruppe abhängiger Optionen mit einer übergeordneten Checkbox zu steuern. Sind nur einige Optionen gewählt, zeigt diese den Zustand «teilweise».

### Regeln.
* Jede Checkbox ist klar beschriftet und benennt die Option eindeutig.
* Zusammengehörige Checkboxes werden gruppiert. Eine Gruppe enthält nicht zu viele Optionen (maximal 5–7).
* Das Label enthält keine weiteren interaktiven Elemente.
* Ohne sichtbaren Text braucht die Checkbox ein `aria-label`.

## Implementation (Web Components, Englisch)

The `<sbb-checkbox>` component provides the same functionality as a native `<input type="checkbox"/>` enhanced with the SBB Design.

### Slots

It is possible to provide a label via an unnamed slot; the component can optionally display a `<sbb-icon>` using
the `iconName` property or via custom SVG using the `icon` slot.
The icon can be placed before or after the label based on the value of the `iconPlacement` property (default: `end`).

```html
<sbb-checkbox value="checkbox">Example</sbb-checkbox>

<sbb-checkbox value="icon" icon-name="tickets-class-small">Icon</sbb-checkbox>

<sbb-checkbox value="start-icon" icon-name="tickets-class-small" icon-placement="start"
  >Icon at start</sbb-checkbox
>
```

### States

The component could be checked or not depending on the value of the `checked` attribute.

```html
<sbb-checkbox value="checked-checkbox" checked>Checked state</sbb-checkbox>
```

It has a third state too, which is set if the `indeterminate` property is true.
This is useful when multiple dependent checkboxes are used
(e.g., a parent which is checked only if all the children are checked, otherwise is in indeterminate state).
Clicking on a `<sbb-checkbox>` in this state sets `checked` to `true` and `indeterminate` to false.

```html
<sbb-checkbox value="indeterminate-checkbox" indeterminate="true">Indeterminate state</sbb-checkbox>
```

The component can be displayed in `disabled` or `required` state by using the self-named properties.

```html
<sbb-checkbox value="required-checkbox" required="true">Required</sbb-checkbox>

<sbb-checkbox value="disabled-checkbox" disabled="true">Disabled</sbb-checkbox>
```

### Style

The component has three possible `size` values, named `xs`, `s` and `m`.

```html
<sbb-checkbox value="size" size="xs">Size</sbb-checkbox>

<sbb-checkbox value="size" size="s">Size</sbb-checkbox>
```

The component's label can be displayed in bold using the `sbb-text--bold` class on a wrapper tag:

```html
<sbb-checkbox value="bold">
  <span class="sbb-text--bold">Bold label</span>
</sbb-checkbox>
```

### Events

Consumers can listen to the native `change` event on the `<sbb-checkbox>` component to intercept the input's change;
the current state can be read from `event.target.checked`, while the value from `event.target.value`.

### Accessibility

The component provides the same accessibility features as the native checkbox.

Avoid adding other interactive controls into the content of `<sbb-checkbox>`, as this degrades the experience for users of assistive technology.

Always provide an accessible label via `aria-label` for checkboxes without descriptive text content.
If you don't want the label to appear next to the checkbox, you can use `aria-label` to specify an appropriate label.

```html
<sbb-checkbox aria-label="Subscribed to email message"></sbb-checkbox>
```

### Complex Values

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

```html
<sbb-checkbox .value=${{value: 'value', name: 'name'}} name="name">Checkbox</sbb-checkbox>
```

## API (Web Components, Englisch)

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