Toast - Canvas Design System

When to Use

Use Toast when: Confirming a completed action (save, delete, copy), showing non-blocking errors, or providing brief feedback that doesn't require user action.

Don't use when: The message requires user attention or blocks a workflow — use an Alert or Modal instead. Avoid stacking more than 3 toasts at once.

Variants

wsToastSuccess('Changes saved!');
wsToastError('Something went wrong');
wsToastWarning('Please review');
wsToastInfo('New updates');

With Action

Toasts can include an action button for undo or follow-up actions.

wsToast('Item deleted', 'info', {
    action: {
        label: 'Undo',
        onClick: function() { wsToastSuccess('Restored!'); }
    }
});

Custom Duration

The default auto-dismiss time is 4 seconds. Pass duration in milliseconds to customise.

wsToastInfo('Quick toast', { duration: 2000 });
wsToastInfo('Long toast', { duration: 8000 });

JavaScript API

Function	Description
`wsToast(message, variant, options)`	Show a toast with full control
`wsToastSuccess(message, options)`	Shorthand for success variant
`wsToastError(message, options)`	Shorthand for error variant
`wsToastWarning(message, options)`	Shorthand for warning variant
`wsToastInfo(message, options)`	Shorthand for info variant

Options

Option	Type	Default	Description
`message`	string	—	Toast message text (required)
`variant`	string	`info`	`success` \| `error` \| `warning` \| `info`
`duration`	number	`4000`	Auto-dismiss time in milliseconds
`closable`	bool	`true`	Show close button
`action.label`	string	`null`	Action button label
`action.onClick`	function	`null`	Action button click handler

PHP Setup

The toast container must be rendered once on the page (usually in the footer). The JS API then creates toasts dynamically inside it.

<?= ws_toast_container() ?>

Anatomy

.ws-toast-container — Fixed-position container (bottom-right)

.ws-toast — Individual toast element

.ws-toast__icon — Variant icon

.ws-toast__message — Message text

.ws-toast__action — Optional action button

.ws-toast__close — Close/dismiss button

CSS Classes

Class	Purpose
`.ws-toast-container`	Fixed container for all toasts
`.ws-toast`	Base toast styles
`.ws-toast--success`	Success variant
`.ws-toast--error`	Error variant
`.ws-toast--warning`	Warning variant
`.ws-toast--info`	Info variant

Files

File	Purpose
`includes/components/helpers.php`	`ws_toast_container()` helper function
`includes/components/toast.php`	Toast container template
`includes/components/components.css`	Toast CSS (`.ws-toast` rules)
`includes/components/components.js`	`wsToast()` and shorthand functions