# Toast

Komponente des SBB Design Systems Lyne.

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

## Links

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

## Elemente

- `sbb-toast`: It displays a toast notification.

## Verwandte Komponenten

- Ähnlich: [Notification](https://digital.sbb.ch/de/design-system/lyne/components/notification/index.md)

## Übersicht

### Was macht die Komponente?
Ein Toast ist eine kurze Benachrichtigung am Bildschirmrand. Er informiert über Ereignisse oder das Ergebnis einer Aktion, ohne den Ablauf zu unterbrechen.

### Wann soll die Komponente eingesetzt werden?
* Um den erfolgreichen Abschluss einer Aktion zu bestätigen.
* Für temporäre Hinweise, die keine zwingende Interaktion erfordern.

### Regeln.
* Der Text ist kurz und prägnant.
* Es kann nur ein Toast gleichzeitig angezeigt werden. Ein neuer Toast ersetzt den vorherigen.
* Wichtige Informationen, z.B. Fehler, gehören nicht nur in einen Toast, da dieser verschwinden kann und für Screenreader-Nutzende belastend ist.
* Aktionen im Toast sind schwer erreichbar. Biete die Aktion zusätzlich an anderer Stelle an.
* Bei Toasts mit Aktion keinen Timeout setzen. Sonst Timeout sinnvoll wählen oder manuelles Schliessen erlauben.
* Toasts erscheinen innerhalb einer Applikation immer an derselben Position.

## Implementation (Web Components, Englisch)

The `<sbb-toast>` is a component that can be used to display toast notifications.

It can be shown/dismissed by calling the `open/close` methods.
Only one toast can ever be opened at one time:
if a new `<sbb-toast>` is opened while a previous message is still showing, the older message will be automatically dismissed.

```html
<sbb-button onclick="document.querySelector('sbb-toast').open()">Open toast</sbb-button>
<sbb-toast>Toast content</sbb-toast>
```

### Important note

You should carefully consider every use of the `<sbb-toast>` component since it can be a source of
stress for people with visual impairments (see the ["Accessibility"](#accessibility) section for more info).

Here are a few tips for correct usage:

- Try to avoid actions inside a `<sbb-toast>` since they are not easily reachable;
- If an action is needed, you should provide an alternative way to perform it;
- If not strictly necessary, use the `polite` (_default_) configuration since it is less aggressive for screen-reader users.

### Slots

It is possible to provide a text via an unnamed slot; the component can optionally display a `<sbb-icon>`
at the component start using the `iconName` property or via custom content using the `icon` slot.

```html
<sbb-button onclick="document.querySelector('sbb-toast').open()">Open toast</sbb-button>
<sbb-toast icon-name="dog-small">Toast content</sbb-toast>
```

A `<sbb-toast>` can also be given a custom action that, if marked with the `sbb-toast-close` attribute, will also dismiss it.

```html
<sbb-button onclick="document.querySelector('sbb-toast').open()">Open toast</sbb-button>
<sbb-toast position="bottom-left">
  Toast content
  <!-- Toast action can be a button -->
  <sbb-transparent-button
    slot="action"
    icon-name="clock-small"
    sbb-toast-close
  ></sbb-transparent-button>
  <!-- Or a link -->
  <sbb-link-button slot="action">Link action</sbb-link-button>
</sbb-toast>
```

### Style

If the `readOnly` property (attribute `readonly`) is set to true, the close button is hidden.
The time before the component automatically closes can be set with the `timeout` property (in milliseconds,
default is 0, which is equal to never closing automatically).

The position on the page where the toast will be opened can be configured with the `position` property,
which accepts all the combinations of the vertical positions `top` and `bottom`
with the horizontal positions `left`, `start`, `center`, `right` and `end` (default: `bottom-center`).

```html
<sbb-button onclick="document.querySelector('sbb-toast').open()">Open toast bottom left</sbb-button>
<sbb-toast position="bottom-left">Toast content</sbb-toast>

<sbb-button onclick="document.querySelector('sbb-toast#top-center').open()">
  Open toast top center with timeout
</sbb-button>
<sbb-toast position="top-center" timeout="20000" id="top-center">Toast content</sbb-toast>
```

### Accessibility

The `<sbb-toast>` announces messages via an aria-live region.
Use the `politeness` property to customize the politeness announcement behavior.
Check [ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#live_regions) for further info.

The `<sbb-toast>` does not move focus to the toast element, because it would disrupt users in the middle of a workflow.

For any action offered in the `<sbb-toast>`, your application should provide an alternative way to perform the action
(e.g. a keyboard combination).

Avoid setting a `timeout` for toasts that have an action available,
as screen reader users may want to navigate to the toast element to activate the action.

#### Known issue

Slotted text is not interpreted correctly by screen readers on Chrome.
To address the problem, the component will automatically wrap any slotted text in a `span` element.
Unless strictly necessary, we advise you not to wrap it preventively and let the component do it for you.

```html
<sbb-toast position="bottom-left">
  <!-- This text would not be read on Chrome -->
  Free text node
</sbb-toast>

<sbb-toast position="bottom-left">
  <span>Toast content</span>
  <!-- This is OK! -->
</sbb-toast>
```

## API (Web Components, Englisch)

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