# Alert

Component of the SBB design system Lyne.

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

## Links

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

## Elements

- `sbb-alert`, several can be combined with `sbb-alert-group`: It displays messages which require user's attention.

## Related components

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

## Overview

### What does the component do?
An alert shows important information or warnings to users. By default, it can be closed. It can also be displayed as non-closable (readonly).

### When should the component be used?
* To inform about critical errors, warnings or important information.
* To bring immediate attention to critical messages.

### Rules.
* An alert contains a title and a clear, concise message.
* Alerts are placed in an alert group. It controls spacing and accessibility (new alerts are announced by screen readers).
* Alerts and [notifications](https://digital.sbb.ch/en/design-system/lyne/components/notification/) are not combined.
* Alerts are not used for error messages in forms.

## Implementation (web components)

The `<sbb-alert>` is a component which should be used to display important messages to a client.

Multiple instances of this component can be used within the `<sbb-alert-group>` component.
The group also manages the accessibility of one or multiple alert instances and also the
visual gap between each other.

```html
<sbb-alert-group accessibility-title="Disruptions" accessibility-title-level="2">
  <sbb-alert size="l">
    <sbb-title level="3">Interruption between Genève and Lausanne</sbb-title>
    The rail traffic between Allaman and Morges is interrupted. All trains are cancelled.
    <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
  </sbb-alert>
  <sbb-alert>
    <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
    Between Berne and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
    construction work will take place. You have to expect changed travel times and changed
    connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
  </sbb-alert>
</sbb-alert-group>
```

### Interactions

If all `<sbb-alert>` instances in a group are dismissed, it's recommended to completely
remove the `<sbb-alert-group>` from DOM.

Listen to the `empty` event dispatched by the group and react accordingly.

### Slots

The unnamed slot is used to project an `<sbb-title>`, text content and one or more `<sbb-link>` elements.

The component can optionally display an `<sbb-icon>` at the component start using the `iconName` property or via custom content using the `icon` slot.

```html
<sbb-alert icon-name="disruption">
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
</sbb-alert>

<sbb-alert>
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  <sbb-icon slot="icon" name="disruption"></sbb-icon>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections. <sbb-link href="https://www.sbb.ch">Find out more</sbb-link>
</sbb-alert>
```

### Readonly

Per default a `<sbb-alert>` can be dismissed by a user. If an alert should not be dismissable,
use the `readonly` attribute/`readOnly` property.

```html
<sbb-alert readonly>
  <sbb-title level="3">Interruption between Berne and Olten</sbb-title>
  Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock
  construction work will take place. You have to expect changed travel times and changed
  connections.
</sbb-alert>
```

### Style

Users can choose between three `size` options: `s`, `m` and `l`.

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

<sbb-alert size="l"> ... </sbb-alert>
```

### Animation

Set the `animation` property to manage which animations are enabled.
As a base rule, opening animations should be active if an alert arrives after the initial page load.

### Accessibility

Accessibility is mainly done by wrapping the alerts into the `<sbb-alert-group>`.

The description text is wrapped into an `<p>` element to guarantee the semantic meaning.

Avoid slotting block elements (e.g. `<div>`) as this violates semantic rules and can have
negative effects on screen readers.

For the `<sbb-alert-group>` it's possible to add a hidden title by specifying the `accessibility-title`.
The heading level can be set via `accessibility-title-level`.

By default, the `<sbb-alert-group>` has the role `status` which means that if a new alert
arrives, it will be read out as soon as the user is idle
(equal to [aria-live="polite"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)).

You can change the `role` or `aria-live` attributes to fit your needs.
For example, you can set the `role` to `alert` which implicitly sets `aria-live` to `assertive`
and therefore interrupts screen reader flow, to immediately read out the alert content.

**Note that with role `alert`, in some combinations of screen readers and browsers not every part of the alert is fully read.**

## API (web components)

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