advanced_toast

A modern, flexible toast notification system for Drupal 10.3+ and Drupal 11 built on Single Directory Components (SDC).

Motivation

Traditional Drupal messages appear at the top of the page, requiring users to scroll up to see feedback after form submissions or actions. Toast notifications solve this by displaying temporary, non-intrusive messages that appear in a fixed position (like bottom-right corner), providing immediate feedback without disrupting the user's workflow.

This module was created to provide a component-based toast system that:

• Integrates seamlessly with Drupal's SDC architecture
• Allows complete theming control without touching module code
• Supports extending with custom toast types per theme
• Provides multiple APIs (PHP, Twig, JavaScript) for maximum flexibility
• Works alongside or replaces standard Drupal messages

Key Features

• Module-based components - Includes status, warning, and error toasts out of the box
• Theme extensibility - Create custom toast types in your theme (e.g., info, celebration, success)
• Multiple APIs - Trigger toasts from PHP services, Twig templates, or JavaScript
• Drupal message replacement - Optionally convert standard Drupal messages to toasts globally
• Three-tier fallback system - Ensures toasts always render even if custom components are missing
• Configurable admin UI - Map unlimited toast types to components with validation
• Accessible - ARIA live regions, keyboard support, respects prefers-reduced-motion
• Server-side rendering - Components render server-side for SEO and accessibility
• Template inheritance - Custom components can extend base toast templates
• Cache-friendly lazy rendering - Toasts render via lazy builders (like Drupal core's status messages), allowing pages to be fully cached while toast content remains session-specific

Simple Example

From PHP

$toast = \Drupal::service('advanced_toast.toast');

// Standard toasts
$toast->status('Your changes have been saved!');
$toast->warning('Please review your submission.');
$toast->error('An error occurred.');

// Custom toast with options
$toast->addToast('Welcome!', 'info', [
  'duration' => 3000,
  'fallback' => 'status',
]);

From Twig

{{ toast_status('Your changes have been saved!') }}
{{ toast_warning('Please review your submission.') }}
{{ toast_error('An error occurred.') }}

From JavaScript

Drupal.toast('Your changes have been saved!', 'status');
Drupal.toast('Please review your submission.', 'warning');

Creating Custom Toast Types

Easily extend with theme-specific toasts:

# themes/custom/mytheme/components/toast-celebration/toast-celebration.component.yml
name: Toast Celebration
thirdPartySettings:
  advanced_toast:
    is_toast_component: true
props:
  type: object
  properties:
    message:
      type: string
  required:
    - message

Map the component at /admin/config/user-interface/toast and use it:

$toast->addToast('🎉 Achievement unlocked!', 'celebration');

Use Cases

• Better UX - Non-intrusive feedback that doesn't require scrolling
• Modern interfaces - Match contemporary web application patterns
• Custom notifications - Create celebration toasts with confetti, promotional toasts, achievements, etc.
• Multi-theme sites - Each theme can define its own toast styles and types
• Consistent feedback - Standardize all user feedback across your application

Requirements

• Drupal 10.3+ or Drupal 11+
• Single Directory Components (SDC) module (included in core)

Documentation

For complete documentation including:

• Configuration guide
• Creating custom toast types
• Theme customization examples
• API reference
• Troubleshooting

See the README.md in the project repository.

Installation

composer require drupal/advanced_toast
drush en advanced_toast
drush cr

Configuration

Visit /admin/config/user-interface/toast to:

• Enable Drupal message replacement
• Configure default duration and position
• Map toast types to SDC components
• Add custom toast types

Credits

Co-authored with Claude Code - AI pair programming assistant by Anthropic.