Toast

Toasts provide brief notifications to the user. They appear temporarily and shouldn't interrupt the user experience.

When to use

• To confirm an action (saved, deleted, updated)
• To show non-critical errors or warnings
• To notify about background processes
• For system updates or status changes
• To provide feedback after user actions

Key features

• Multiple variants - Default, success, warning, error, and info
• Auto-dismiss - Configurable duration or persistent
• Action buttons - Optional actions like undo or retry
• Progress indicator - Shows time remaining
• Queueing - Multiple toasts stack nicely
• Programmatic control - Show, close, and manage via JavaScript
• Accessible - Screen reader announcements

Anatomy

A toast consists of:

• Container - The toast wrapper
• Title - Primary message
• Description - Additional details (optional)
• Close button - Manual dismiss option
• Action - Optional button for actions
• Progress bar - Visual countdown for auto-dismiss

Installation

npm install @pm7/core

CSS Classes

Data Attributes

Basic Usage

import { showToast } from '@pm7/core';

// Show a simple toast
showToast({
  title: 'Success!',
  description: 'Your changes have been saved.'
});

JavaScript API

showToast(options)

Toast Variants

// Default toast
showToast({
  title: 'Notification',
  description: 'This is a default toast message.'
});

// Success toast
showToast({
  title: 'Success!',
  description: 'Operation completed successfully.',
  variant: 'success'
});

// Warning toast
showToast({
  title: 'Warning',
  description: 'Please review your input.',
  variant: 'warning'
});

// Error/Destructive toast
showToast({
  title: 'Error',
  description: 'Something went wrong.',
  variant: 'destructive'
});

// Info toast
showToast({
  title: 'Information',
  description: 'New updates are available.',
  variant: 'info'
});

Advanced Options

// Custom duration
showToast({
  title: 'Quick message',
  duration: 3000  // 3 seconds
});

// Persistent toast
showToast({
  title: 'Action required',
  description: 'Please complete your profile.',
  duration: 0  // Won't auto-dismiss
});

// Toast with action
showToast({
  title: 'File deleted',
  description: 'document.pdf has been deleted.',
  action: '<button class="pm7-button pm7-button--sm pm7-button--primary">Undo</button>'
});

// Toast with callback
showToast({
  title: 'Saved',
  description: 'Your preferences have been saved.',
  onClose: () => {
    console.log('Toast closed');
  }
});

Manual Control

import { showToast, closeToast, closeAllToasts } from '@pm7/core';

// Show toast and get ID
const toastId = showToast({
  title: 'Processing...',
  duration: 0  // Don't auto-dismiss
});

// Close specific toast
setTimeout(() => {
  closeToast(toastId);
}, 5000);

// Close all toasts
closeAllToasts();

React Usage

import { useToast } from '@pm7/react';

function MyComponent() {
  const { toast } = useToast();

  const handleSave = () => {
    // Save logic...
    toast({
      title: 'Saved successfully',
      description: 'Your changes have been saved.',
      variant: 'success'
    });
  };

  return (
    <button onClick={handleSave}>Save</button>
  );
}

Accessibility

• Toasts appear in a fixed position (top-right corner)
• Close button includes aria-label="Close" for screen readers
• Focus remains on the trigger element
• Toast actions are keyboard accessible
• Each toast has a unique ID for programmatic control

Best Practices

• Keep it brief - Toast messages should be concise
• Non-blocking - Don't use toasts for critical information
• Appropriate variant - Use the correct variant for the message type
• Timing - Default 5 seconds is good for most messages
• Actionable - Include an action button when appropriate

Copy this link that can be used as documentation for working with this component: