# Toast

Component of the SBB design system Lyne.

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

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/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

## Elements

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

## Related components

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

## Overview

### What does the component do?
A toast is a short notification at the edge of the screen. It informs about events or the result of an action without interrupting the flow.

### When should the component be used?
* To confirm the successful completion of an action.
* For temporary notices that do not necessarily require interaction.

### Rules.
* The text is short and concise.
* Only one toast can be shown at a time. A new toast replaces the previous one.
* Important information, e.g. errors, does not belong in a toast alone, as it can disappear and is burdensome for screen reader users.
* Actions in a toast are hard to reach. Also offer the action elsewhere.
* Do not set a timeout for toasts with an action. Otherwise choose a sensible timeout or allow manual closing.
* Within an application, toasts always appear in the same position.

## Implementation (web components)

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)

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