# Notification

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/notification/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-notification--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/notification/overview (API: https://lyne-angular.app.sbb.ch/angular/components/notification/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-43
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/notification

## Elements

- `sbb-notification`: It displays messages which require a user's attention without interrupting its tasks.

## Related components

- Similar: [Alert](https://digital.sbb.ch/en/design-system/lyne/components/alert/index.md), [Toast](https://digital.sbb.ch/en/design-system/lyne/components/toast/index.md)

## Overview

### What does the component do?
A notification informs users within the content about the status of an action or other important notices, without interrupting their task. The types are info, note, success, warn and error.

### When should the component be used?
* To inform users in a flow about the status of actions, e.g. success or error.
* To point out required actions or changes.
* For system-wide, very important messages, use the alert component instead.

### Rules.
* The notification is placed at the top of the main content or close to the affected element. Positioning is consistent throughout the application.
* The text is short and clear. A title is optional.
* The notification does not disappear automatically. It stays until users close it or the problem is resolved.
* The close button is optional. If the message must be read, omit it (`readonly`).
* Newly appearing notifications must be announced to screen readers (`aria-live="polite"` on the container).

## Implementation (web components)

The `<sbb-notification>` is a component which purpose is to inform users of updates.
A notification is an element that displays a brief, important message
in a way that attracts the user's attention without interrupting the user's task.

Inline notifications show up in task flows, to notify users of an action status or other information.
They usually appear at the top of the primary content area or close to the item needing attention.

The `<sbb-notification>` is structured in the following way:

- Icon: informs users of the notification type at a glance.
- Title (optional): gives users a quick overview of the notification.
- Close button (optional): closes the notification.
- Message: provides additional detail and/or actionable steps for the user to take.

```html
<sbb-notification>
  <sbb-title level="3">Notification title</sbb-title>
  The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
  <sbb-link href="/">Link one</sbb-link>
  <sbb-link href="/">Link two</sbb-link>
  <sbb-link href="/">Link three</sbb-link>
</sbb-notification>
```

Note that the notification only supports inline links.

### Variants

The `<sbb-notification>` supports the types `info` (default), `note`, `success`, `warn` and `error`, based on the type of the information displayed.

```html
<sbb-notification type="success">...</sbb-notification>

<sbb-notification type="warn">...</sbb-notification>

<sbb-notification type="error">...</sbb-notification>
```

### States

It is possible to display the component in `readonly` state by using the self-named property.
In this case, the close button will not be shown.

```html
<sbb-notification readonly> ... </sbb-notification>
```

### Interactions

Inline notifications do not dismiss automatically.
They persist on the page until the user dismisses them or takes action that resolves the notification.

By default, a close button is displayed to dismiss inline notifications. Including the close button is optional
and should not be included if it is critical for a user to read or interact with the notification by setting the `readonly` property to `true`.

### Style

If the `<sbb-notification>` host needs a margin, in order to properly animate it on open/close,
we suggest using the `--sbb-notification-margin` variable to set it.
For example, use `--sbb-notification-margin: 0 0 var(--sbb-spacing-fixed-4x) 0` to apply a bottom margin.

### Accessibility

In order to announce the notification's content to screen readers as it becomes visible,
consumers **must** use the `aria-live` attribute with the `polite` value on the component's container.
This ensures that users who rely on screen readers are promptly informed of any relevant updates or changes.

```html
<!-- Add here any incoming notification by adding a sbb-notification component. -->
<div id="notification-container" aria-live="polite">
  <sbb-notification type="success">Task successfully completed.</sbb-notification>
</div>
```

### Animation

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

## API (web components)

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