sp-toast

NPM 1.6.0

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

<sp-toast> elements display brief, temporary notifications. They are noticeable but do not disrupt the user experience and do not require an action to be taken.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/toast

Import the side effectful registration of <sp-toast> via:

import '@spectrum-web-components/toast/sp-toast.js';

When looking to leverage the Toast base class as a type and/or for extension purposes, do so via:

import { Toast } from '@spectrum-web-components/toast';

Anatomy

The toast consists of two key parts:

  • The message content in its default slot
  • An optional action button using slot="action"

Content

The message in its default slot:

<sp-toast open>
    This is important information that you should read, soon.
</sp-toast>

Action Button

An optional action using slot="action":

<sp-toast open>
    This is important information that you should read, soon.
    <sp-button
        slot="action"
        static-color="white"
        variant="secondary"
        treatment="outline"
    >
        Do something
    </sp-button>
</sp-toast>

Options

Width and Wrapping

The toast can be constrained to a specific width, and its content will wrap accordingly:

<sp-toast open style="width: 300px">
    This is important information that you should read, soon.
    <sp-button
        slot="action"
        static-color="white"
        variant="secondary"
        treatment="outline"
    >
        Do something
    </sp-button>
</sp-toast>

Variants

By default, the toast is rendered in gray and does not have an icon. This is used when the message is neutral in tone or when its semantics do not fit in any of the other variants.

However, the toast supports several variants to convey different types of messages:

Use variant="negative" to show an error or failure.

<sp-toast open variant="negative">
    This is negative information that you should read, soon.
</sp-toast>

Use variant="positive" to show a successful action or completion of a task.

<sp-toast open variant="positive">
    This is positive information that you should read, soon.
</sp-toast>

Use variant="info" to show an informative message.

<sp-toast open variant="info">
    This is information that you should read.
</sp-toast>

Behaviors

Timeout

The toast can be configured to automatically dismiss itself after a specified duration. For accessibility reasons, the minimum timeout is 6000ms (6 seconds). For longer messages, it's recommended to add 1000ms for every 120 words.

<sp-toast open timeout="6000">
    This message will disappear after 6 seconds.
</sp-toast>

Close Events

The toast dispatches a close event when it's being closed, either by user action or timeout. This event can be prevented using event.preventDefault().

Accessibility

Keyboard Interaction

The toast supports keyboard navigation:

  • When an action button is present, it can be accessed using the Tab key
  • The close button (when present) can be activated using Enter or Space

Place toasts in a region

The <sp-toast> element is rendered with a role of alert to notify screen readers. When rendering a toast on a page, it should be placed in a container with a role of region for better accessibility.

<div role="region" aria-label="Toast Notifications">
    <sp-toast open>
        This is important information that you should read, soon.
    </sp-toast>
</div>

Allow time for reading

Accessibility concerns require that a Toast is available for at least 6000ms before being dismissed.

The toast ensures that messages are visible for a minimum of 6 seconds to give users enough time to read and comprehend the information. For longer messages, the timeout is automatically extended.

It is suggested that messages longer than 120 words should receive an additional 1000ms in their timeout for each additional 120 words in the message.

For example, a message with 240 words should have a timeout of 7000ms, and a message with 360 words should have a timeout of 8000ms.

Provide appropriate labels

  • The toast's variant icon includes an appropriate icon-label for screen readers (e.g., "Information" for info variant)
  • Action buttons should have clear, descriptive labels
<sp-toast open variant="negative" icon-label="Warning">
    This is important information that you should read, soon.
    <sp-button
        slot="action"
        static-color="white"
        variant="secondary"
        treatment="outline"
    >
        Ignore warning
    </sp-button>
</sp-toast>

Patch Changes

  • #5349 a9727d2 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies [f6cebbd, 00eb0a8]:

    • @spectrum-web-components/icons-workflow@1.6.0
    • @spectrum-web-components/button@1.6.0
    • @spectrum-web-components/icon@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [4e06533]:
    • @spectrum-web-components/button@1.5.0
    • @spectrum-web-components/icon@1.5.0
    • @spectrum-web-components/icons-workflow@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/button@1.4.0
    • @spectrum-web-components/icon@1.4.0
    • @spectrum-web-components/icons-workflow@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/button@1.3.0
    • @spectrum-web-components/icon@1.3.0
    • @spectrum-web-components/icons-workflow@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/toast

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/toast

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/toast

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Bug Fixes

  • toast: adds iconLabel to address accessibility (#4944) (8121057)

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/toast

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/toast

0.49.0 (2024-10-15)

Features

  • add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/toast

0.48.0 (2024-09-17)

Bug Fixes

  • toast: added ability to wrap toast content with long words (#4738) (302d6fe)

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/toast

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/toast

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/toast

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/toast

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/toast

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/toast

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/toast

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/toast

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/toast

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/toast

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/toast

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/toast

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/toast

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/toast

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/toast

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/toast

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/toast

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/toast

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/toast

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/toast

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/toast

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/toast

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/toast

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/toast

0.39.1 (2023-10-06)

Bug Fixes

  • progress-circle,toast,tooltip: ensure complete dependency graph (#3701) (a5dfada)

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/toast

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/toast

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/toast

0.36.0 (2023-08-18)

Bug Fixes

  • close button static white (d324017)
  • toast: switches toast[open] to use visibility hidden to fix overlay handling (#3511) (8428cad), closes #3510

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/toast

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/toast

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/toast

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/toast

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/toast

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/toast

0.30.0 (2023-05-03)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)
  • ensure browser understandable extensions (f4e59f7)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • toast: ensure "close" event only triggers when open===false (7fa08ba)
  • toast: include dependencies (1b82212)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • add and use icons-ui package (d9c3ab2)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • pass through autocomplete attribute to inputs (5416510)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • toast: add "sp-toast" pattern (d0a5f00)
  • toast: default to "open === false", always dispatch "close" event (fcb3729)
  • toast: update spectrum css input (183ee95)
  • update lit-* dependencies, wip (377f3c8)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.11.16 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/toast

0.11.15 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/toast

0.11.14 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/toast

0.11.13 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/toast

0.11.12 (2023-02-13)

Note: Version bump only for package @spectrum-web-components/toast

0.11.11 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/toast

0.11.10 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/toast

0.11.9 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/toast

0.11.8 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/toast

0.11.7 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/toast

0.11.6 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/toast

0.11.5 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/toast

0.11.4 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/toast

0.11.3 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/toast

0.11.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/toast

0.11.1 (2022-08-24)

Note: Version bump only for package @spectrum-web-components/toast

0.11.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.10.14 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/toast

0.10.13 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/toast

0.10.12 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/toast

0.10.11 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/toast

0.10.10 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/toast

0.10.9 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/toast

0.10.8 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/toast

0.10.7 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/toast

0.10.6 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/toast

0.10.5 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/toast

0.10.4 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/toast

0.10.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/toast

0.10.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/toast

0.10.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/toast

0.10.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.9.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/toast

0.9.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.8.17 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/toast

0.8.16 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/toast

0.8.15 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/toast

0.8.14 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.8.13 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/toast

0.8.12 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/toast

0.8.11 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/toast

0.8.10 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/toast

0.8.9 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/toast

0.8.8 (2021-05-24)

Note: Version bump only for package @spectrum-web-components/toast

0.8.7 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/toast

0.8.6 (2021-04-15)

Note: Version bump only for package @spectrum-web-components/toast

0.8.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/toast

0.8.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/toast

0.8.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/toast

0.8.2 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/toast

0.8.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/toast

0.8.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.7.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.7.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/toast

0.7.1 (2021-01-28)

Note: Version bump only for package @spectrum-web-components/toast

0.7.0 (2021-01-21)

Bug Fixes

  • toast: ensure "close" event only triggers when open===false (7fa08ba)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • toast: default to "open === false", always dispatch "close" event (fcb3729)
  • toast: update spectrum css input (183ee95)

0.6.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • use icons without "size" values (3fc7c91)
  • use latest @spectrum-css/* versions (c35eb86)

Features

  • action-button: add action button pattern (03ac00a)
  • toast: default to "open === false", always dispatch "close" event (fcb3729)
  • toast: update spectrum css input (183ee95)

0.5.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/toast

0.5.3 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.5.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.5.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/toast

0.5.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)

0.4.4 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/toast

0.4.3 (2020-07-27)

Note: Version bump only for package @spectrum-web-components/toast

0.4.2 (2020-07-24)

Bug Fixes

  • ensure browser understandable extensions (f4e59f7)

0.4.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/toast

0.4.0 (2020-07-17)

Features

  • leverage "exports" field in package.json (321abd7)

0.3.4 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/toast

0.3.3 (2020-05-12)

Note: Version bump only for package @spectrum-web-components/toast

0.3.2 (2020-05-08)

Note: Version bump only for package @spectrum-web-components/toast

0.3.1 (2020-04-21)

Note: Version bump only for package @spectrum-web-components/toast

0.3.0 (2020-04-16)

Features

  • add and use icons-ui package (d9c3ab2)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.2.5 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/toast

0.2.4 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/toast

0.2.3 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/toast

0.2.2 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/toast

0.2.1 (2020-02-01)

Note: Version bump only for package @spectrum-web-components/toast

0.2.0 (2020-01-30)

Features

  • pass through autocomplete attribute to inputs (5416510)

0.1.2 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/toast

0.1.1 (2019-12-12)

Bug Fixes

  • toast: include dependencies (1b82212)

0.1.0 (2019-12-09)

Features

  • toast: add "sp-toast" pattern (d0a5f00)

Attributes and Properties

Property Attribute Type Default Description iconLabel icon-label string | undefined The `iconLabel` property is used to set the `label` attribute on the icon element. This is used to provide a text alternative for the icon to ensure accessibility.

If the iconLabel property is not set, the icon will use the variant to dynamically set the label.

open open boolean false The `open` property indicates whether the toast is visible or hidden. timeout timeout number | null null When a timeout is provided, it represents the number of milliseconds from when the Toast was placed on the page before it will automatically dismiss itself.

Accessibility concerns require that a Toast is available for at least 6000ms before being dismissed, so any timeout of less than 6000ms will be raised to that baseline.

It is suggested that messages longer than 120 words should receive an additional 1000ms in their timeout for each additional 120 words in the message.

For example, a message with 240 words should have a timeout of 7000ms, and a message with 360 words should have a timeout of 8000ms.

variant variant ToastVariants The variant applies specific styling when set to `negative`, `positive`, `info`, `error`, or `warning`.

The variants error and warning are deprecated and should be replaced with negative.

variant attribute is removed when not matching one of the above.

Slots

Name Description default slot The toast content action button element surfacing an action in the Toast

Events

Name Type Description close CustomEvent Announces that the Toast has been closed by the user or by its timeout.