← Back to Components

Toast Component

The Toast component displays temporary notification messages that overlay the UI and automatically disappear after a set duration. It provides visual feedback for user actions, system events, or important notifications. Toast notifications can be displayed at fixed screen positions or relative to the user’s cursor.

Usage

<!-- Basic usage -->
<qds-toast
  type="success"
  message="Operation completed successfully"
  duration="3000"
  position="top-right">
</qds-toast>

// Using the component directly
const toast = document.createElement('qds-toast');
toast.setAttribute('message', 'This is a toast message');
toast.setAttribute('type', 'success');
document.body.appendChild(toast);
toast.show();

// Using the global toast manager (recommended)
QdsToastManager.success('Operation completed successfully');
QdsToastManager.error('An error occurred');
QdsToastManager.warning('Warning: This action cannot be undone');
QdsToastManager.info('Informational message');

// Custom options
QdsToastManager.show('Custom toast', {
  type: 'info',
  duration: 5000,
  position: 'bottom-center'
});

Attributes

Name	Type	Default	Description
type	String	'info'	The type of toast message: ‘info’, ‘success’, ‘warning’, ‘error’
message	String	''	The message text to display in the toast
duration	Number	3000	Duration in milliseconds before the toast auto-dismisses
position	String	'top-right'	Position on screen: ‘top-right’, ‘top-left’, ‘bottom-right’, ‘bottom-left’, ‘top-center’, ‘bottom-center’, ‘cursor’
cursor-x	Number	0	X position of cursor when using ‘cursor’ position (automatically set)
cursor-y	Number	0	Y position of cursor when using ‘cursor’ position (automatically set)
cursor-offset	Number	10	Offset in pixels from cursor position

CSS Parts

The component’s shadow DOM structure can be styled using CSS ::part selectors:

Part	Description
container	The toast container element
icon	The icon element
message	The text message element
close-button	The close button element

Events

Event	Detail	Description
qds-toast-show	{ type, message }	Fired when the toast is shown
qds-toast-hide	{ type, message }	Fired when the toast is hidden

Methods

Method	Description
show()	Shows the toast
hide()	Hides the toast

Global Toast Manager

The component registers a global QdsToastManager object that provides convenient methods for showing toasts:

Method	Parameters	Description
show(message, options)	message: String, options: Object	Shows a toast with the specified message and options
success(message, options)	message: String, options: Object	Shows a success toast
error(message, options)	message: String, options: Object	Shows an error toast
warning(message, options)	message: String, options: Object	Shows a warning toast
info(message, options)	message: String, options: Object	Shows an info toast

The options object can include:

• duration: Number (in milliseconds)
• position: String (one of the position values)

Styling

The toast uses CSS variables from the theme for consistent styling:

:host {
  --toast-info-color: var(--theme-info, #445E89);
  --toast-success-color: var(--theme-success, #00BE34);
  --toast-warning-color: var(--theme-warning, #FFA300);
  --toast-error-color: var(--theme-error, #8B1F00);
  --toast-text-color: var(--theme-text-inverse, #FFFFFF);
  --toast-background: var(--theme-background-primary, #FFFFFF);
  --toast-shadow: var(--theme-shadow, rgba(0, 0, 0, 0.1));
}

Accessibility

• Uses role="alert" to indicate the toast is an important and usually time-sensitive message
• Uses aria-live="polite" to announce the toast message to screen readers
• The close button has an aria-label="Close" for screen readers
• Toast automatically dismisses after a configurable duration
• Provides visual indicators through colors and icons to convey message type

Browser Support

Works in all modern browsers:

• Chrome
• Firefox
• Safari
• Edge

Examples

Basic Toast

QdsToastManager.info('This is a basic toast message');

Success Toast

QdsToastManager.success('Operation completed successfully');

Error Toast

QdsToastManager.error('An error occurred');

Custom Position and Duration

QdsToastManager.warning('This warning will appear at the bottom center for 5 seconds', {
  position: 'bottom-center',
  duration: 5000
});

Cursor Position

// Display the toast near the cursor position
document.addEventListener('click', (event) => {
  QdsToastManager.info('Toast appears at cursor position', {
    position: 'cursor',
    event: event,
    cursorOffset: 15
  });
});

Listening for Toast Events

document.addEventListener('qds-toast-show', (e) => {
  console.log('Toast shown:', e.detail);
});

document.addEventListener('qds-toast-hide', (e) => {
  console.log('Toast hidden:', e.detail);
});