What does the component do?

A toast is a short-term notification that appears at the edge of the screen to inform users about certain events, successes or errors.

When should the component be used?

• To inform users about the successful completion of an action.
• To display temporary information or notifications that do not require user interaction.
• To quickly communicate errors or warnings.

Rules

• Toasts should be clear and concise to get the message across quickly.
• Toasts should appear in a consistent position on the screen within a web page or application.
• Toasts should disappear automatically after a reasonable time or be able to be closed manually.

Playground

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.

<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" 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.

<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.

<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).

<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 behaviour.
Check ARIA 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.

<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>

Properties

Methods

Events

CSS Properties

Slots