# Toggle

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: main element with parts; use parts only within the element they belong to
- Categories: Form
- Status: Design guidelines complete

## Links

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

## Elements

- `sbb-toggle`: It can be used as a container for two `sbb-toggle-option`, acting as a toggle button.
  - `sbb-toggle-option`, only within `sbb-toggle`: It displays a toggle option within a `sbb-toggle`.

## Overview

### What does the component do?
A toggle consists of two options that users switch between to change the view of the content, e.g. "List" and "Map".

### When should the component be used?
* To switch between equivalent views of the same content.

### Rules.
* The options are labelled briefly, with text, icon or both.
* Exactly one option is always selected.
* For on/off settings, use the [toggle check](https://digital.sbb.ch/en/design-system/lyne/components/toggle-check/); for navigation, use [tabs](https://digital.sbb.ch/en/design-system/lyne/components/tabs/).

## Implementation (web components)

The `<sbb-toggle>` component is a wrapper for `<sbb-toggle-option>` elements
that can be selected by the user; it is useful for switching between views within the content.

```html
<sbb-toggle value="Value 1">
  <sbb-toggle-option value="Value 1" icon-name="arrow-right-small">Bern</sbb-toggle-option>
  <sbb-toggle-option value="Value 2" icon-name="arrows-right-left-small">Zürich</sbb-toggle-option>
</sbb-toggle>
```

### Configuration

#### `<sbb-toggle>`

The `even` property can be used to let the component expand to the parent component or adapt to the label's width.

The component has two different sizes, `s` and `m`, which can be set using the `size` property.

```html
<sbb-toggle size="s" even> ... </sbb-toggle>
```

#### `<sbb-toggle-option>`

It is possible to provide a label via an unnamed slot; the component can optionally display an `<sbb-icon>`
at the component start using the `iconName` property or via custom content using the `icon` slot.
Text and icon are not exclusive and can be used together.

```html
<sbb-toggle-option value="Value" icon-name="app-icon-small"></sbb-toggle-option>

<sbb-toggle-option value="Value" icon-name="app-icon-small">Option</sbb-toggle-option>
```

### Complex Values

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

```ts
const values = [
  { value: 'value 1', name: 'Option 1' },
  { value: 'value 2', name: 'Option 2' },
];
```

```html
<sbb-toggle .value="${values[0]}" name="name">
  <sbb-toggle-option .value="${values[0]}">Option 1</sbb-toggle-option>
  <sbb-toggle-option .value="${values[1]}">Option 2</sbb-toggle-option>
</sbb-toggle>
```

## API (web components)

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