Toasts

Introduction

Toasts in Chassis CSS provide lightweight, temporary notifications that appear briefly to inform users without interrupting their workflow. Unlike notification components that persist until dismissed, toasts are designed for transient messaging that communicates status updates, confirmations, or non-critical information.

How they work

The Toast component in Chassis CSS operates on an opt-in initialization model for optimal performance, featuring flexible positioning and accessible design:

• Toasts appear over content without disrupting user interaction
• Toasts require JavaScript initialization for functionality
• Built-in timing controls for self-hiding behavior with configurable timing
• Full lifecycle events for integration with application logic
• Stack and position anywhere using Chassis's utility system
• ARIA attributes and screen reader support built-in
• Consistent with your design system and Figma components
• Multiple toasts naturally stack when using container elements

Interactive example

The following example demonstrates a toast that appears in response to user interaction, featuring automatic dismissal and the standard header-body structure.

The JavaScript that powers this interactive example:

const toastTrigger = document.getElementById('liveToastButton')
const toastLiveExample = document.getElementById('liveToast')

if (toastTrigger) {
  const toastChassis = chassis.Toast.getOrCreateInstance(toastLiveExample)
  toastTrigger.addEventListener('click', () => {
    toastChassis.show()
  })
}

Examples

Explore practical toast implementations covering structure variations, positioning strategies, and customization approaches. These examples demonstrate Chassis CSS's flexible toast system in real-world scenarios.

Standard structure

Chassis CSS toasts follow a predictable structure optimized for accessibility and visual consistency. The recommended pattern includes a header section with metadata and actions, plus a body section for the primary message content.

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded me-xsmall" alt="...">
    <strong class="me-auto">Chassis</strong>
    <small>11 mins ago</small>
    <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

Visual transparency

Toasts use semi-transparent backgrounds to blend naturally with underlying content, creating subtle visual layering that doesn't compete with your interface design.

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded me-xsmall" alt="...">
    <strong class="me-auto">Chassis</strong>
    <small class="fg-subtle">11 mins ago</small>
    <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

Stacking behavior

Toast containers automatically handle vertical stacking with appropriate spacing. Multiple toasts within a container will stack naturally with consistent spacing between items.

<div class="toast-container position-static">
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-xsmall" alt="...">
      <strong class="me-auto">Chassis</strong>
      <small class="fg-subtle">just now</small>
      <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      See? Just like this.
    </div>
  </div>

  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-xsmall" alt="...">
      <strong class="me-auto">Chassis</strong>
      <small class="fg-subtle">2 seconds ago</small>
      <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Heads up, toasts will stack automatically
    </div>
  </div>
</div>

Simplified layouts

Create streamlined toasts by customizing the structure with Chassis's utility classes. This example removes the header component and uses flexbox utilities for a minimalist approach.

<div class="toast align-items-center" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="close-button me-xsmall m-auto" data-cx-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

Action integration

Toasts can include interactive elements like buttons for user actions. Consider accessibility implications when adding controls to auto-hiding toasts.

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-body">
    Hello, world! This is a toast message.
    <div class="mt-xsmall pt-xsmall border-top">
      <button type="button" class="button primary small">Take action</button>
      <button type="button" class="button secondary small" data-cx-dismiss="toast">Close</button>
    </div>
  </div>
</div>

Color customization

Apply Chassis's color and background utilities to create themed toast variants. Combine with appropriate close button variants for optimal contrast.

<div class="toast align-items-center bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="close-button close-button-white me-xsmall m-auto" data-cx-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

Positioning system

Toast positioning leverages Chassis's utility classes for flexible placement anywhere in your interface. Common patterns include corner positioning and centered layouts.

Dynamic positioning

This interactive example demonstrates various positioning options using utility classes.

<form>
  <div class="mb-medium">
    <label for="selectToastPlacement">Toast placement</label>
    <select class="form-select mt-xsmall" id="selectToastPlacement">
      <option value="" selected>Select a position...</option>
      <option value="top-0 start-0">Top left</option>
      <option value="top-0 start-50 translate-middle-x">Top center</option>
      <option value="top-0 end-0">Top right</option>
      <option value="top-50 start-0 translate-middle-y">Middle left</option>
      <option value="top-50 start-50 translate-middle">Middle center</option>
      <option value="top-50 end-0 translate-middle-y">Middle right</option>
      <option value="bottom-0 start-0">Bottom left</option>
      <option value="bottom-0 start-50 translate-middle-x">Bottom center</option>
      <option value="bottom-0 end-0">Bottom right</option>
    </select>
  </div>
</form>
<div aria-live="polite" aria-atomic="true" class="bg-even position-relative cxd-example-toasts rounded-3">
  <div class="toast-container p-medium" id="toastPlacement">
    <div class="toast">
      <div class="toast-header">
        <img src="..." class="rounded me-xsmall" alt="...">
        <strong class="me-auto">Chassis</strong>
        <small>11 mins ago</small>
      </div>
      <div class="toast-body">
        Hello, world! This is a toast message.
      </div>
    </div>
  </div>
</div>

Notification areas

For applications that generate multiple notifications, establish dedicated notification areas using positioned containers.

<div aria-live="polite" aria-atomic="true" class="position-relative">
  <!-- Position it: -->
  <!-- - `.toast-container` for spacing between toasts -->
  <!-- - `top-0` & `end-0` to position the toasts in the upper right corner -->
  <!-- - `.p-medium` to prevent the toasts from sticking to the edge of the container  -->
  <div class="toast-container top-0 end-0 p-medium">

    <!-- Then put toasts within -->
    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded me-xsmall" alt="...">
        <strong class="me-auto">Chassis</strong>
        <small class="fg-subtle">just now</small>
        <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
      </div>
      <div class="toast-body">
        See? Just like this.
      </div>
    </div>

    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded me-xsmall" alt="...">
        <strong class="me-auto">Chassis</strong>
        <small class="fg-subtle">2 seconds ago</small>
        <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
      </div>
      <div class="toast-body">
        Heads up, toasts will stack automatically
      </div>
    </div>
  </div>
</div>

Centered alignment

Use flexbox utilities for center-aligned toasts within their container.

<!-- Flexbox container for aligning the toasts -->
<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center w-100">

  <!-- Then put toasts within -->
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-xsmall" alt="...">
      <strong class="me-auto">Chassis</strong>
      <small>11 mins ago</small>
      <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

Accessibility

Toast accessibility in Chassis CSS follows WCAG guidelines and best practices for temporary notifications. Proper implementation ensures screen reader compatibility and keyboard accessibility.

ARIA attributes and live regions

Toasts require specific ARIA attributes to work effectively with assistive technologies:

• Use aria-live to announce content changes to screen readers, setting it to "assertive" for critical messages like errors and urgent notifications, or "polite" for informational messages such as confirmations and updates
• Set aria-atomic="true" to ensure the entire toast is announced as a complete unit rather than just the changed portions, preventing fragmented announcements
• Apply the appropriate role attribute using "alert" for critical messages or "status" for informational updates to provide semantic context

The live region must exist in the DOM before the toast is generated or updated to ensure proper announcement by assistive technologies.

<!-- Critical message -->
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <!-- Toast content -->
</div>

<!-- Informational message -->
<div class="toast" role="status" aria-live="polite" aria-atomic="true">
  <!-- Toast content -->
</div>

Timing and interaction guidelines

Consider these accessibility requirements when implementing toast timing and interactive features:

• Ensure users have adequate time to read content before dismissal. Adjust the delay option for longer messages or complex content
• When using autohide: false, always include a close button to maintain user control and keyboard accessibility
• Avoid adding focusable elements (buttons, links) to auto-hiding toasts, as users may not have sufficient time to interact with them

<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-cx-autohide="false">
  <div class="toast-header">
    <img src="..." class="rounded me-xsmall" alt="...">
    <strong class="me-auto">Chassis</strong>
    <small>11 mins ago</small>
    <button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

When to use alternatives

For form errors or process-critical information, consider using the notification component instead of toasts. Notifications provide persistent messaging better suited for important information that requires user attention.

CSS

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Custom properties

These CSS variables control the component's appearance and can be modified dynamically on the page. Components use cascading variables, allowing seamless variations in size, color, and style without redundant style declarations through component inheritance and the context class system.

--#{$prefix}zindex: var(--#{$prefix}toast-zindex, #{$zindex-toast});
--#{$prefix}padding-y: var(--#{$prefix}toast-padding-y, #{$toast-padding-y});
--#{$prefix}padding-x: var(--#{$prefix}toast-padding-x, #{$toast-padding-x});
--#{$prefix}spacing: var(--#{$prefix}toast-spacing, #{$toast-spacing});
--#{$prefix}max-width: var(--#{$prefix}toast-max-width, #{$toast-max-width});
@include rfs($toast-font-size, --#{$prefix}font-size);
--#{$prefix}fg-color: var(--#{$prefix}toast-fg-color, #{$toast-fg-color});
--#{$prefix}bg-color: var(--#{$prefix}toast-bg-color, #{$toast-bg-color});
--#{$prefix}border-width: var(--#{$prefix}toast-border-width, #{$toast-border-width});
--#{$prefix}border-color: var(--#{$prefix}toast-border-color, #{$toast-border-color});
--#{$prefix}border-radius: var(--#{$prefix}toast-border-radius, #{$toast-border-radius});
--#{$prefix}box-shadow: var(--#{$prefix}toast-box-shadow, #{$toast-box-shadow});
--#{$prefix}header-fg-color: var(--#{$prefix}toast-header-fg-color, #{$toast-header-fg-color});
--#{$prefix}header-bg-color: var(--#{$prefix}toast-header-bg-color, #{$toast-header-bg-color});
--#{$prefix}header-border-color: var(--#{$prefix}toast-border-color, #{$toast-header-border-color});

Sass variables

These Sass variables are also exposed as CSS custom properties using the --cx- prefix. A Sass variable $variable-name becomes available as --cx-variable-name in CSS, allowing for styles to be modified dynamically on the page. See the context components page for more details.

$toast-max-width:                   22.5rem; //360px;
$toast-padding-x:                   .75rem;
$toast-padding-y:                   .5rem;
$toast-font-size:                   .875rem;
$toast-fg-color:                    var(--#{$prefix}fg-main);
$toast-bg-color:                    #{to-opacity(var(--#{$prefix}bg-main), var(--#{$prefix}opacity-dim-main))};
$toast-border-width:                var(--#{$prefix}border-width-medium);
$toast-border-color:                var(--#{$prefix}border-subtle);
$toast-border-radius:               var(--#{$prefix}border-radius-medium);
$toast-box-shadow:                  $shadow-default-40;
$toast-spacing:                     $container-padding-x;

$toast-header-fg-color:             var(--#{$prefix}fg-subtle);
$toast-header-bg-color:             #{to-opacity(var(--#{$prefix}bg-main), var(--#{$prefix}opacity-dim-main))};
$toast-header-border-color:         $toast-border-color;

JavaScript API

Control toast behavior programmatically with Chassis CSS's comprehensive JavaScript interface, featuring initialization, configuration, and lifecycle management.

Initialization

Initialize toast components via JavaScript:

const toastElements = document.querySelectorAll('.toast')
const toasts = [...toastElements].map(element => new chassis.Toast(element, options))

Triggers

Automatic toast dismissal can be triggered through data attributes without requiring manual JavaScript initialization.

Enable dismissal with the data-cx-dismiss attribute on a button within the toast:

<button type="button" class="close-button" data-cx-dismiss="toast" aria-label="Dismiss"></button>

Or on a button outside the toast using the additional data-cx-target attribute:

<button type="button" class="close-button" data-cx-dismiss="toast" data-cx-target="#my-toast" aria-label="Dismiss toast"></button>

Configuration options

Customize toast behavior through JavaScript options or HTML data attributes for flexible integration with your application logic.

Chassis components offer flexible configuration through both data attributes and JavaScript. To use data attributes, prefix any option with data-cx- followed by the option name in kebab-case format (using hyphens instead of camelCase). For example, write data-cx-custom-class="my-class" rather than data-cx-customClass="my-class".

For more complex configurations, Chassis provides the data-cx-config attribute which accepts a JSON string of multiple settings. This approach simplifies markup when configuring several options at once. If the same option appears in both data-cx-config and as a separate data attribute (like data-cx-title), the individual attribute takes precedence. You can also use JSON values in individual attributes, such as data-cx-delay='{"show":100,"hide":200}' for more granular control.

When initializing components, Chassis merges configurations from multiple sources in this priority order: default settings, data-cx-config values, individual data-cx-* attributes, and finally any JavaScript object options. Values defined later in this sequence override earlier ones.

Methods

Programmatically control toast instances with these JavaScript methods for showing, hiding, and managing toast lifecycle.

Basic usage examples:

const toast = chassis.Toast.getOrCreateInstance('#myToast')
toast.show()

// Hide a toast manually
toast.hide()

// Check visibility
if (toast.isShown()) {
  console.log('Toast is currently visible')
}

Events

The Toast component provides lifecycle events for integration with application logic:

Event handling example:

const toastElement = document.getElementById('myToast')

toastElement.addEventListener('hidden.cx.toast', event => {
  // Toast has been hidden - clean up or trigger next action
  console.log('Toast was dismissed')
})

toastElement.addEventListener('shown.cx.toast', event => {
  // Toast is now visible - start any timers or tracking
  console.log('Toast is now visible')
})