Toast
Toasts are temporary notifications that appear in the bottom-right corner and dismiss automatically. They require JavaScript (assets/js/toast.js).
Toast uses data-type for semantic message types, the same attribute and vocabulary as callout. Both are feedback components where the type describes what the message means, not just what colour to show.
Basic usage
Include the script on any page that uses toasts:
<script src="/assets/js/toast.js"></script>
Then call showToast() from JavaScript:
showToast('Changes saved successfully.');
Types
Use the second argument to set the message type. The JS sets data-type on the toast element, which drives the CSS colour.
showToast('Changes saved.', 'success');
showToast('Connection unstable.', 'warning');
showToast('Failed to save.', 'danger');
showToast('New version available.', 'info');
Each variant takes its text colour from the matching --status-* token, and keeps it in both light and dark themes. Only the neutral toast inverts with the theme.
JavaScript
API
showToast(message, type, duration);
| Parameter | Type | Default | Description |
|---|---|---|---|
message |
string | – | Toast message text (required) |
type |
string | 'default' |
'default', 'success', 'warning', 'danger', 'info' |
duration |
number | 4000 |
Auto-dismiss time in milliseconds |
HTML structure
The JS creates this markup automatically:
<div class="toast-container" aria-live="polite" aria-atomic="false">
<div class="toast" data-type="success" role="alert">
<span class="toast-message">Changes saved.</span>
<button class="button close-btn" type="button" data-icon-only data-size="small" aria-label="Dismiss">
<div class="svg-icn" data-icon="close">...</div>
</button>
</div>
</div>
The container is injected once at the end of <body>. Individual toasts are appended and removed automatically.
Accessibility
- The container uses
aria-live="polite"so screen readers announce new toasts - Each toast has
role="alert" - The dismiss button has
aria-label="Dismiss" - Toasts auto-dismiss after the specified duration, users can also dismiss manually
Usage rules
Do
- Use toasts for transient, non-blocking feedback (save confirmations, status updates)
- Keep messages short and actionable
Don't
- Don't use toasts for critical errors that require user action. Use a modal or inline alert
- Don't stack more than 3 toasts simultaneously
CSS reference
This section documents how the component is built. For usage, see the sections above.
Styling
The neutral toast, meaning one with no data-type, inverts with the theme:
| Property | Value (Light) | Value (Dark) |
|---|---|---|
| Background | ||
| Text colour |
A typed toast keeps its status colour as text in both themes and reads its surface from the paired token:
| Property | Value (Light) | Value (Dark) |
|---|---|---|
| Background | var(--status-*-bg) |
var(--status-*-bg) |
| Text colour | var(--status-*) |
var(--status-*) |
Both halves come from the tokens because the pair now flips together: in dark mode --status-*-bg is derived from the page ground pulled toward the status colour, holding every variant above 7.7:1. The toast previously re-derived its own dark surface to work around the --status-*-bg token gap; that patch is retired.
Selectors
| Selector | Purpose |
|---|---|
| Fixed position container (bottom-right), holds all toasts | |
| Individual toast: background, text colour, layout | |
.toast[data-type="success"], .toast[data-type="green"] |
Success colour variant |
.toast[data-type="warning"], .toast[data-type="yellow"] |
Warning colour variant |
.toast[data-type="danger"], .toast[data-type="red"] |
Danger colour variant |
.toast[data-type="info"], .toast[data-type="blue"] |
Info colour variant |
| Message text span | |
.toast .button.close-btn |
Dismiss button — the shared role class, re-pointed to the toast's own currentColor |
Deprecated bespoke dismiss button, kept for existing markup. Use .button.close-btn |
Use in another product
The design system installs once per product:
npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0
This component's styles ship in design-system.css. Its behaviour ships as dist/js/toast.js — copy it into the product's served assets and include it once per page:
<script src="assets/js/toast.js" defer></script>
In React, render this contract through the packaged adapter instead of writing the markup by hand:
import { showToast } from '@bydefaultstudio/design-system/react';
The adapter renders the contract above and bridges this component's events to props — see React.