# Toggle-Check

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: one element
- Categories: Form
- Status: Design guidelines complete

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/design-system/lyne/components/toggle-check/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-toggle-check--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/toggle-check/overview (API: https://lyne-angular.app.sbb.ch/angular/components/toggle-check/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=31104-566771
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/toggle-check

## Elements

- `sbb-toggle-check`: It displays a toggle checkbox.

## Related components

- Similar: [Checkbox](https://digital.sbb.ch/en/design-system/lyne/components/checkbox/index.md)

## Overview

### What does the component do?
A toggle check switches between two states, e.g. "on" and "off". It behaves like a [checkbox](https://digital.sbb.ch/en/design-system/lyne/components/checkbox/).

### When should the component be used?
* To switch a function or setting on or off that takes effect immediately.

### Rules.
* For selections in forms that only apply after submission, use the checkbox.
* The toggle check needs a label. Without a visible label, set an `aria-label`.
* Do not place further interactive elements in the label.

## Implementation (web components)

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

```html
<sbb-toggle-check name="check" value="single-checkbox">Example</sbb-toggle-check>
```

### 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 content using the `icon` slot.
The icon can be at the component start or end based on the value of the `labelPosition` property (default: `after`).

```html
<sbb-toggle-check name="check" value="single-checkbox" icon-name="pie-small">
  Example
</sbb-toggle-check>

<sbb-toggle-check name="other" value="single-checkbox" icon-name="pie-small" label-position="start">
  Another example
</sbb-toggle-check>
```

### States

The component can be displayed in `checked` or `disabled` states using the self-named properties.

```html
<sbb-toggle-check name="check" value="Value" checked>Option</sbb-toggle-check>

<sbb-toggle-check name="other" value="Value" disabled>Option</sbb-toggle-check>
```

### Style

The component has three different sizes (`xs`, `s` and `m`),
which can be changed using the `size` property.

```html
<sbb-toggle-check size="m" value="single-checkbox"> Example in m size</sbb-toggle-check>

<sbb-toggle-check size="xs" value="single-checkbox"> Example in xs size </sbb-toggle-check>
```

### Events

Consumers can listen to the native `change` event on the `<sbb-toggle-check>` component to intercept the input's change;
the current state can be read from `event.target.checked` and 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-toggle-check>`, as this degrades the experience for users of assistive technology.

If you don't want the label to appear next to the `<sbb-toggle-check>` component,
you can not provide it and then use `aria-label` to specify an appropriate label for screen-readers.

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

### Complex Values

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

```html
<sbb-toggle-check .value=${{value: 'value', name: 'name'}} name="name">Toggle Check</sbb-toggle-check>
```

## API (web components)

Full API tables (attributes, events, slots, CSS properties): https://digital.sbb.ch/en/design-system/lyne/components/toggle-check/api.md