Toast

<cs-toast>

Stable

Since 0.1

Toasts display brief, non-blocking notifications that appear temporarily above the page content.

Show notification

<div id="toast-basic">
  <cs-button appearance="filled">Show notification</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-basic');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', () => {
    toast.create('This is a toast notification!');
  });
</script>

Now Available in Cornerstone Core
Toast moved over from Pro in 3.11.0. On an earlier Core version? Upgrade to use it.

Adding a single <cs-toast> element to the page gives you the ability to dispatch notifications at any time. Toast notifications appear in a stack that renders in the top layer, showing above everything else on the page.

You can put the <cs-toast> element anywhere in the DOM, as long as it’s somewhere inside the <body>. In most apps, a single toast element is optimal.

Toasts carry unique accessibility challenges.
Read the accessibility considerations before using them — thoughtful implementation can mitigate the issues.

Overlapping toasts on this page are intentional, not a bug.
This page has many <cs-toast> elements to show off the component — most apps need only one.

Examples

Variant

Set the variant option to brand, success, warning, danger, or neutral to change the type of notification.

    Neutral
    Brand
    Success
    Warning
    Danger
  

<div id="toast-variant">
  <div class="cs-cluster cs-gap-xs">
    <cs-button appearance="filled" data-variant="neutral" data-icon="gear">Neutral</cs-button>
    <cs-button appearance="filled" data-variant="brand" data-icon="circle-info">Brand</cs-button>
    <cs-button appearance="filled" data-variant="success" data-icon="check">Success</cs-button>
    <cs-button appearance="filled" data-variant="warning" data-icon="circle-exclamation">Warning</cs-button>
    <cs-button appearance="filled" data-variant="danger" data-icon="triangle-exclamation">Danger</cs-button>
  </div>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-variant');
  const toast = container.querySelector('cs-toast');

  container.addEventListener('click', event => {
    const button = event.target.closest('[data-variant]');
    if (!button) return;

    const variant = button.getAttribute('data-variant');
    const icon = button.getAttribute('data-icon');

    toast.create(`This is a ${variant} notification`, {
      variant,
      icon,
    });
  });
</script>

Size

Set the size option to xs, s, m, l, or xl to change the size of the toast item.

    Extra Small
    Small
    Medium
    Large
    Extra Large
  

<div id="toast-size">
  <div class="cs-cluster cs-gap-xs">
    <cs-button appearance="filled" data-size="xs" data-icon="shrimp">Extra Small</cs-button>
    <cs-button appearance="filled" data-size="s" data-icon="mouse-field">Small</cs-button>
    <cs-button appearance="filled" data-size="m" data-icon="horse">Medium</cs-button>
    <cs-button appearance="filled" data-size="l" data-icon="elephant">Large</cs-button>
    <cs-button appearance="filled" data-size="xl" data-icon="whale">Extra Large</cs-button>
  </div>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-size');
  const toast = container.querySelector('cs-toast');

  container.addEventListener('click', event => {
    const button = event.target.closest('[data-size]');
    if (!button) return;

    const size = button.getAttribute('data-size');
    const icon = button.getAttribute('data-icon');

    toast.create(`This is a ${size} notification`, {
      size,
      icon,
    });
  });
</script>

Icons

Pass an icon option to display an icon at the start of the toast item. You can pass a simple string for the icon name, or an object with additional options like library, family, and variant.

Show notification with icon

<div id="toast-icons">
  <cs-button appearance="filled">Show notification with icon</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-icons');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', () => {
    toast.create('Your message has been sent successfully!', {
      variant: 'success',
      icon: 'send',
    });
  });
</script>

For more control over the icon, pass an object with name and optional library, family, or variant properties.

    Filled icon
    Brand icon
  

<div id="toast-icons-advanced">
  <div class="cs-cluster cs-gap-xs">
    <cs-button appearance="filled">Filled icon</cs-button>
    <cs-button appearance="filled">Brand icon</cs-button>
  </div>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-icons-advanced');
  const toast = container.querySelector('cs-toast');
  const buttons = container.querySelectorAll('cs-button');

  buttons[0].addEventListener('click', () => {
    toast.create('This uses a rounded, filled icon!', {
      variant: 'brand',
      icon: {
        name: 'notifications',
        family: 'rounded',
        variant: 'fill',
      },
    });
  });

  buttons[1].addEventListener('click', () => {
    toast.create('Follow us on GitHub!', {
      variant: 'neutral',
      icon: {
        name: 'github',
        library: 'brands',
      },
    });
  });
</script>

Duration

Set the duration option to control how long notifications show before disappearing. The value is in milliseconds and defaults to 5000 (5 seconds). A value of 0 will keep the notification open until the user dismisses it.

    3 seconds
    10 seconds
    Until dismissed
  

<div id="toast-duration">
  <div class="cs-cluster cs-gap-xs">
    <cs-button appearance="filled" data-duration="3000">3 seconds</cs-button>
    <cs-button appearance="filled" data-duration="10000">10 seconds</cs-button>
    <cs-button appearance="filled" data-duration="0">Until dismissed</cs-button>
  </div>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-duration');
  const toast = container.querySelector('cs-toast');

  container.addEventListener('click', event => {
    const button = event.target.closest('[data-duration]');
    if (!button) return;

    const duration = parseInt(button.getAttribute('data-duration'));

    toast.create(duration > 0 ? `This will disappear in ${duration / 1000} seconds` : 'Dismiss me manually!', {
      duration,
      variant: 'brand',
    });
  });
</script>

Placement

Use the placement attribute to set the position of the toast stack on the screen.

  
    top-start
    top-center
    top-end
    bottom-start
    bottom-center
    bottom-end
  
  Show notification

<div id="toast-placement">
  <cs-select label="Placement" value="top-end">
    <cs-option value="top-start">top-start</cs-option>
    <cs-option value="top-center">top-center</cs-option>
    <cs-option value="top-end">top-end</cs-option>
    <cs-option value="bottom-start">bottom-start</cs-option>
    <cs-option value="bottom-center">bottom-center</cs-option>
    <cs-option value="bottom-end">bottom-end</cs-option>
  </cs-select>
  <br />
  <cs-button appearance="filled">Show notification</cs-button>
  <cs-toast placement="top-end"></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-placement');
  const toast = container.querySelector('cs-toast');
  const select = container.querySelector('cs-select');
  const button = container.querySelector('cs-button');

  select.addEventListener('change', () => {
    toast.placement = select.value;
  });

  button.addEventListener('click', () => {
    toast.create('This notification appears at ' + toast.placement, {
      variant: 'brand',
      icon: 'location_on',
    });
  });
</script>

Hover & Focus Behavior

Toast items automatically pause their countdown timer when you hover over them or when the close button receives focus. This gives users more time to read the content before it disappears. When the mouse leaves or focus moves away, the timer resets and starts counting down again.

Show notification (hover to pause)

<div id="toast-pause">
  <cs-button appearance="filled">Show notification (hover to pause)</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-pause');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', () => {
    toast.create('Hover over me to pause the countdown timer!', {
      duration: 5000,
      variant: 'brand',
      icon: 'schedule',
    });
  });
</script>

Using HTML Content

Set allowHtml to true to render HTML content in notifications. Make sure you trust the content to avoid XSS vulnerabilities.

Show notification with HTML

<div id="toast-html">
  <cs-button appearance="filled">Show notification with HTML</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-html');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', () => {
    toast.create(
      `
      <cs-icon slot="icon" name="notifications"></cs-icon>
      <strong>New message!</strong><br>
      You have <em>3 unread messages</em> in your inbox.
    `,
      {
        allowHtml: true,
        variant: 'brand',
        duration: 0,
      },
    );
  });
</script>

Responding to Custom Buttons

You can add custom buttons or other interactive elements to a toast item using allowHtml. Use the returned toast item reference to query for your elements and attach event listeners.

Show notification with button

<div id="toast-custom-button">
  <cs-button appearance="filled">Show notification with button</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-custom-button');
  const toast = container.querySelector('cs-toast');
  const showButton = container.querySelector('cs-button');

  showButton.addEventListener('click', async () => {
    const toastItem = await toast.create(
      `
      <cs-icon slot="icon" name="redeem"></cs-icon>
      You have a new reward!
      <div style="margin-block-start: var(--cs-space-xs);">
        <cs-button class="claim-button" variant="brand" size="s">Claim</cs-button>
        <cs-button class="dismiss-button" appearance="filled" size="s">No Thanks</cs-button>
      </div>
    `,
      {
        allowHtml: true,
        variant: 'brand',
        duration: 0,
      },
    );

    const claimButton = toastItem.querySelector('.claim-button');
    const dismissButton = toastItem.querySelector('.dismiss-button');

    // When the claim button is clicked
    claimButton.addEventListener('click', () => {
      //
      // Add custom claim logic here
      //
      toastItem.hide();
    });

    // When the dismiss button is clicked
    dismissButton.addEventListener('click', () => {
      toastItem.hide();
    });
  });
</script>

Responding to Events

The create() method returns a promise that resolves to the generated toast item. You can use this reference to add event listeners.

Show notification

<div id="toast-events">
  <cs-button appearance="filled">Show notification</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-events');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', async () => {
    const toastItem = await toast.create('Click me or let me disappear...', {
      variant: 'brand',
      icon: 'touch_app',
    });

    toastItem.addEventListener('click', () => {
      console.log('Toast item was clicked!');
    });

    toastItem.addEventListener('cs-after-hide', () => {
      console.log('Toast item was dismissed');
    });
  });
</script>

Creating Toast Items Manually

While toast.create() is the easiest way to show notifications, you can also create <cs-toast-item> elements manually. This approach gives you full control over the toast item’s content and is useful when you need to add custom elements or complex layouts.

Create toast item manually

<div id="toast-append">
  <cs-button appearance="filled">Create toast item manually</cs-button>
  <cs-toast></cs-toast>
</div>

<script type="module">
  const container = document.getElementById('toast-append');
  const toast = container.querySelector('cs-toast');
  const button = container.querySelector('cs-button');

  button.addEventListener('click', () => {
    const toastItem = document.createElement('cs-toast-item');
    toastItem.variant = 'brand';
    toastItem.innerHTML = `
      <cs-icon slot="icon" name="pets" variant="fill"></cs-icon>
      This notification was created manually!
    `;

    toast.prepend(toastItem);
  });
</script>

Accessibility Considerations

Toasts have a number of accessibility limitations. For example:

Due to their transient nature, toasts can be missed entirely by screen magnifier users and difficult to perceive for others depending on their visual and cognitive abilities.
Due to their DOM placement and vague position in a page’s reading order, toasts can be difficult for keyboard users to navigate to.
Due to their positioning on the page, toasts can obscure other essential elements, especially for users who use browser or OS zooming features.

Rarely will toasts offer the best usability for all of your users, so consider if other UX patterns, like dialogs or inline messages, offer a better experience. If toasts are the right fit for your use case, consider these tips:

Keep toasts short and sweet.
Set the duration to 5000 ms (5 seconds) or longer to give users enough time to locate and understand the toast item.
Consider allowing users to adjust the timing. While the duration of a toast item resets on hover (see Hover & Focus Behavior), a setting in your application can allow users to control the timing of toasts to best suit their needs and abilities.
Choose a consistent placement for toasts in your application and stick with it. Otherwise, users need to guess where transient notifications will appear and risk missing them entirely.
If a transient toast item contains an action, ensure that action is available elsewhere on the page. This ensures that users can still execute the action even if they miss the toast.

API

Importing

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.

npm

Self-Hosted

React

import '@cruglobal/cornerstone-components/components/toast/toast.js';

import './cornerstone/components/toast/toast.js';

import CsToast from '@cruglobal/cornerstone-components/react/toast/index.js';

Slots

Learn more about using slots.

Name	Description
(default)	Place `<cs-toast-item>` elements here to show them as notifications.

Attributes & Properties

Learn more about attributes and properties.

Property	Attribute	Description	Type	Default	Reflects
`placement`	`placement`	The placement of the toast stack on the screen.	`'top-start' \| 'top-center' \| 'top-end' \| 'bottom-start' \| 'bottom-center' \| 'bottom-end'`	`'top-end'`	Yes

Methods

Learn more about methods.

Name	Description	Arguments
`create()`	Creates a toast notification programmatically and adds it to the stack. Returns a reference to the created toast item element.	`message: string, options: ToastCreateOptions`

CSS Custom Properties

Learn more about CSS custom properties.

Name	Description	Default
`--gap`	The gap between stacked toast items.	`var(--cs-space-s)`
`--width`	The width of the toast stack.	`28rem`

Custom States

Learn more about custom states.

Name	Description	CSS selector
`visible`	Applied when the toast stack has one or more visible toast items.	`:state(visible)`

CSS Parts

Learn more about CSS parts.

Name	Description	CSS selector
`stack`	The container that holds the toast items.	`::part(stack)`

Dependencies

This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.

Quick Links

Recent Searches