Pending Review

Pending Review from User Experience (UX)

Toast Component

Overview

The PWC Toast component provides contextual notification messaging with multiple severity levels, positioning options, and interactive capabilities. Built with variant-specific icons, colors, and positioning controls, it delivers user feedback through temporary or persistent messages that support user workflows with success confirmations, error alerts, warnings, and informational updates.

Core Capabilities

Multi-Variant Messaging - Support for error, warning, success, info, and tip variants with distinct icons and color-coded styling
Flexible Positioning - Inline, upper-right, upper-center, and form positioning options for different notification contexts
Interactive Elements - Optional close button, action buttons, and link slots for user interaction and message management
Content Structure - Heading and message content with typography support and slot-based extensibility for complex notifications
Width Configuration - Standard and wide layout options to accommodate different content lengths and display requirements
Close Management - Configurable close functionality with event handling for notification dismissal and state management

When to use Toast:

User feedback scenarios requiring immediate attention such as form validation errors, success confirmations, and system alerts
Status notifications for background processes, data operations, and system state changes that require user awareness
Contextual help and guidance messages that provide tips, warnings, or informational content related to user actions
Temporary messaging needs where notifications should appear prominently but allow dismissal when no longer relevant

When not to use Toast:

Permanent status indicators where persistent components provide better visibility and continuous user reference
Complex dialog scenarios where modal components offer better interaction patterns and focused user attention
Subtle notifications where less prominent components avoid disrupting user workflow and visual focus

Basic Implementation

React 18React 19+AngularPure JavaScript

import { PwcToast } from "@progress-i360/pwc-react";
import { useState } from 'react';

function BasicToast() {
  const [showToast, setShowToast] = useState(false);

  return (
    <>
      {showToast && (
        <PwcToast
          variant="success"
          heading="Success!"
          message="Operation completed successfully."
          onClose={() => setShowToast(false)}
        />
      )}
      <button type="button" onClick={() => setShowToast(true)}>
        Show Toast
      </button>
    </>
  );
}

import { useEffect, useRef, useState } from 'react';
import '@progress-i360/progress-web-components/toast';

type ToastElement = HTMLElement & {
  heading?: string;
  message?: string;
  variant?: string;
  position?: string;
  open?: boolean;
};

function NotificationToast() {
  const toastRef = useRef<ToastElement | null>(null);
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    const toastElement = toastRef.current;
    if (!toastElement) {
      return;
    }

    toastElement.heading = 'Information';
    toastElement.message = 'New update available.';
    toastElement.variant = 'info';
    toastElement.position = 'upper-right';
    toastElement.open = isOpen;

    const handleClose = () => {
      setIsOpen(false);
    };

    toastElement.addEventListener('pwc-close', handleClose);
    return () => {
      toastElement.removeEventListener('pwc-close', handleClose);
    };
  }, [isOpen]);

  return (
    <>
      <pwc-toast ref={toastRef}></pwc-toast>
      <button type="button" onClick={() => setIsOpen(true)}>
        Show Toast
      </button>
    </>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@progress-i360/progress-web-components/button";
import "@progress-i360/progress-web-components/link";
import "@progress-i360/progress-web-components/toast";

@Component({
  selector: 'toast-demo',
  template: `
    <div class="notification-center">
      <pwc-toast 
        *ngIf="showSuccessToast"
        heading="Success!" 
        message="Your changes have been saved successfully."
        variant="success"
        position="upper-right"
        [wide]="false"
        (pwc-close)="hideToast('success')">
        <pwc-button slot="buttons" label="View Details" variant="outline" size="s" (pwc-click)="viewDetails()"></pwc-button>
      </pwc-toast>

      <pwc-toast 
        *ngIf="showErrorToast"
        heading="Error" 
        message="Unable to save changes. Please check your connection and try again."
        variant="error"
        position="upper-center"
        [wide]="true"
        (pwc-close)="hideToast('error')">
        <pwc-link slot="link" href="#" label="Learn more about this error"></pwc-link>
        <pwc-button slot="buttons" label="Retry" variant="primary" size="s" (pwc-click)="retryAction()"></pwc-button>
      </pwc-toast>

      <pwc-toast 
        *ngIf="showWarningToast"
        heading="Warning" 
        message="You have unsaved changes that will be lost."
        variant="warning"
        position="form"
        [noClose]="true"
        (pwc-close)="hideToast('warning')">
        <pwc-button slot="buttons" label="Save" variant="primary" size="s" (pwc-click)="saveChanges()"></pwc-button>
        <pwc-button slot="buttons" label="Discard" variant="outline" size="s" (pwc-click)="discardChanges()"></pwc-button>
      </pwc-toast>

      <pwc-toast 
        *ngIf="showInfoToast"
        message="New features are available in your dashboard."
        variant="info"
        position="inline"
        (pwc-close)="hideToast('info')">
        <pwc-link slot="link" href="#" label="Explore new features"></pwc-link>
      </pwc-toast>

      <pwc-toast 
        *ngIf="showTipToast"
        heading="Pro Tip" 
        message="Use keyboard shortcuts to work faster!"
        variant="tip"
        position="upper-right"
        (pwc-close)="hideToast('tip')">
      </pwc-toast>
    </div>

    <div class="demo-controls">
      <pwc-button label="Show Success" variant="primary" (pwc-click)="showToast('success')"></pwc-button>
      <pwc-button label="Show Error" variant="danger" (pwc-click)="showToast('error')"></pwc-button>
      <pwc-button label="Show Warning" variant="warning" (pwc-click)="showToast('warning')"></pwc-button>
      <pwc-button label="Show Info" variant="info" (pwc-click)="showToast('info')"></pwc-button>
      <pwc-button label="Show Tip" variant="outline" (pwc-click)="showToast('tip')"></pwc-button>
    </div>

    <div class="toast-status" *ngIf="hasActiveToasts">
      <p>Active notifications: {{ getActiveToastCount() }}</p>
    </div>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ToastDemo {
  showSuccessToast = false;
  showErrorToast = false;
  showWarningToast = false;
  showInfoToast = false;
  showTipToast = false;

  get hasActiveToasts() {
    return this.showSuccessToast || this.showErrorToast || this.showWarningToast || this.showInfoToast || this.showTipToast;
  }

  showToast(type: 'success' | 'error' | 'warning' | 'info' | 'tip') {
    // Hide all toasts first
    this.hideAllToasts();

    // Show the requested toast
    switch (type) {
      case 'success':
        this.showSuccessToast = true;
        this.autoHideToast('success', 3000);
        break;
      case 'error':
        this.showErrorToast = true;
        break;
      case 'warning':
        this.showWarningToast = true;
        break;
      case 'info':
        this.showInfoToast = true;
        this.autoHideToast('info', 5000);
        break;
      case 'tip':
        this.showTipToast = true;
        this.autoHideToast('tip', 4000);
        break;
    }
  }

  hideToast(type: 'success' | 'error' | 'warning' | 'info' | 'tip') {
    switch (type) {
      case 'success':
        this.showSuccessToast = false;
        break;
      case 'error':
        this.showErrorToast = false;
        break;
      case 'warning':
        this.showWarningToast = false;
        break;
      case 'info':
        this.showInfoToast = false;
        break;
      case 'tip':
        this.showTipToast = false;
        break;
    }
  }

  hideAllToasts() {
    this.showSuccessToast = false;
    this.showErrorToast = false;
    this.showWarningToast = false;
    this.showInfoToast = false;
    this.showTipToast = false;
  }

  autoHideToast(type: 'success' | 'error' | 'warning' | 'info' | 'tip', delay: number) {
    setTimeout(() => {
      this.hideToast(type);
    }, delay);
  }

  getActiveToastCount(): number {
    let count = 0;
    if (this.showSuccessToast) count++;
    if (this.showErrorToast) count++;
    if (this.showWarningToast) count++;
    if (this.showInfoToast) count++;
    if (this.showTipToast) count++;
    return count;
  }

  viewDetails() {
    console.log('Viewing success details...');
    this.hideToast('success');
  }

  retryAction() {
    console.log('Retrying action...');
    this.hideToast('error');
    // Simulate retry success
    setTimeout(() => {
      this.showToast('success');
    }, 1000);
  }

  saveChanges() {
    console.log('Saving changes...');
    this.hideToast('warning');
    this.showToast('success');
  }

  discardChanges() {
    console.log('Discarding changes...');
    this.hideToast('warning');
  }
}

import '@progress-i360/progress-web-components/toast';

const toast = document.createElement('pwc-toast');
toast.variant = 'success';
toast.heading = 'Success!';
toast.message = 'Your changes have been saved successfully.';

toast.addEventListener('pwc-close', () => {
  console.log('Toast closed');
});

document.body.appendChild(toast);

setTimeout(() => {
  toast.remove();
}, 5000);

Usage Patterns

Form Validation Feedback - Success confirmations, error alerts, and validation messages that provide immediate user feedback
System Status Notifications - Process completion alerts, background task updates, and system state change notifications
User Guidance Messages - Contextual tips, help information, and onboarding guidance that supports user workflows
Alert Management Systems - Warning notifications, critical alerts, and informational updates requiring user attention

Best Practices

Content Strategy Guidelines

Clear Message Hierarchy - Use headings for primary message identification and body text for detailed explanations or context
Appropriate Variant Selection - Choose variants that accurately reflect message severity and user action requirements
Concise Content Writing - Keep messages brief while providing sufficient context for user understanding and decision making
Actionable Language - Use clear, direct language that guides users toward appropriate responses or next steps

Performance Optimization

Controlled Toast Lifecycle - Implement proper show/hide patterns with automatic dismissal timers to prevent notification accumulation
Event Handler Management - Use efficient event handling patterns and proper cleanup to prevent memory leaks in toast-heavy applications
Position Strategy Optimization - Choose positioning strategies that minimize layout reflow and maintain responsive design integrity
Batch Operation Handling - Manage multiple simultaneous toasts with queue systems and consolidation patterns for better user experience

Integration Architecture

Notification System Design - Build centralized toast management systems that handle multiple notification types and lifecycle management
State Management Integration - Connect toast notifications with application state management for consistent user feedback workflows
Accessibility Standards - Ensure proper ARIA attributes, screen reader announcements, and keyboard navigation for inclusive notification experiences
Theme Integration Patterns - Implement consistent color schemes and styling patterns that align with overall application design systems

Common Use Cases

Data Table Headers

Form submission confirmations with success messages and next step guidance for user workflow completion
Data operation feedback including save confirmations, deletion alerts, and bulk operation status notifications
Validation error displays with specific field guidance and correction instructions for form completion assistance

Search Result Sections

Search operation status notifications including result counts, filter applications, and query processing feedback
Export and download completion alerts with file status information and access instructions for user convenience
Search suggestion tips and query optimization guidance to improve user search experience and result quality

Real-time system alerts including performance warnings, connectivity issues, and operational status updates
Data refresh notifications with timestamp information and automatic update confirmations for dashboard reliability
Feature announcement toasts highlighting new capabilities, system updates, and user interface enhancements

Troubleshooting

Common Issues

Actions Not Triggering

Symptoms: Close button doesn't work, toast doesn't appear, or event handlers don't fire properly

Solutions:

Verify that event handlers are properly bound using .bind(this) pattern and component instance references are maintained
Check that toast positioning calculations work correctly and components render in expected DOM locations
Ensure that toast lifecycle management handles show/hide states appropriately with proper timing and state synchronization

Actions Not Visible

Symptoms: Toast doesn't render, close button missing, or content doesn't display properly

Solutions:

Confirm that toast positioning styles work correctly for different position values and viewport constraints
Check that variant-specific styling applies properly with correct colors, icons, and border treatments
Verify that content rendering handles empty states and optional properties appropriately for different use cases

Layout Issues

Symptoms: Toast appears in wrong position, overlaps other content, or doesn't fit responsive layouts properly

Solutions:

Use appropriate z-index values and positioning strategies to ensure toast appears above other interface elements
Check that responsive design accommodates different screen sizes and toast width configurations effectively
Ensure that toast positioning doesn't interfere with existing layout systems and maintains visual hierarchy

Icon Problems

Symptoms: Variant icons don't display, close icon missing, or icon colors don't match theme properly

Solutions:

Verify that variant-specific icons (warning-diamond, warning-alt, checkmark, information-filled, help-filled) are available in icon system
Check that icon color theming works correctly with variant-based color mapping and theme integration
Ensure that close icon functionality works properly without interfering with toast content interaction patterns

Implementation Support

Notification System Architecture - Best practices for building centralized toast management systems with queue handling and lifecycle control
Content Strategy Guidelines - Comprehensive guidance for writing effective toast messages with appropriate tone and actionable content
Accessibility Compliance - WCAG guidelines implementation, screen reader optimization, and keyboard navigation patterns for inclusive notifications

Resources

Storybook Documentation

For comprehensive API documentation, interactive examples, and testing tools: 📖 View Complete API Documentation in Storybook →

This guide provides high-level implementation guidance. For detailed API specifications and interactive examples, visit our Storybook documentation.

Toast Component

Overview

Core Capabilities

Basic Implementation

Usage Patterns

Best Practices

Content Strategy Guidelines

Performance Optimization

Integration Architecture

Common Use Cases

Data Table Headers

Search Result Sections

Dashboard Widget Headers

Troubleshooting

Common Issues

Actions Not Triggering

Actions Not Visible

Layout Issues

Icon Problems

Implementation Support

Resources

Storybook Documentation