🍞 Flutter Easy Messages

A powerful, elegant, and highly customizable Flutter package for displaying toast notifications and snackbars. Built for both simple notifications and complex enterprise scenarios like API error handling, file operations, and request tracking.

---

✨ Features Overview

🎯 Core Features

• 🍞 Toast Notifications - Overlay-based notifications with smooth animations and multiple styling options
• 📱 Responsive Snackbars - Automatic sizing that adapts to mobile, tablet, and desktop screens
• 🎨 Message Types - 4 pre-styled message types: Error, Success, Info, Warning
• 📍 9 Position Options - Complete positioning flexibility: top/center/bottom with left/center/right alignment
• ⚡ Smooth Animations - Customizable entry, exit, and pulse animations with preset speeds
• 🔄 Queue & Replace Modes - Control how multiple messages are handled (queue sequentially or replace)
• 📲 Full Responsiveness - Automatic layout adjustments for all screen sizes and orientations
• ♿ Accessibility - Screen reader integration with semantic labels for inclusive apps
• 🎯 Smart Config - Global defaults with per-message overrides for maximum flexibility

🚀 Advanced Features (Enterprise-Ready)

• 🔘 Action Buttons - Add interactive retry, cancel, or custom buttons to toasts
• 📋 Expandable Error Details - Display detailed error information that users can expand on demand
• ⏳ Persistent Toasts - Long-running operation toasts that don't auto-dismiss
• 👆 Dismissible Toasts - User-controlled dismissal with intuitive tap-to-close gesture
• 🆔 Request ID Tracking - Track and manage toasts by request ID for API correlation
• 📞 Lifecycle Callbacks - React to toast lifecycle events (onShown, onDismissed)
• 📝 Custom Text Styling - Full control over font size, weight, family, and alignment
• 🌐 Context-Free Toasts - Show toasts anywhere in your app without BuildContext
• 🎯 Deduplication - Built-in prevention of duplicate messages
• 📳 Haptic Feedback (Vibration) - Optional iOS/Android vibration tied to message type, zero dependencies, zero permissions

---

🎬 Demo

Message Types & Colors	Snackbars
Toast Positions (9 Options)	Custom Styling & Icons
Animations & Durations

---

🚀 Quick Start (2 Steps!)

Step 1: Add to Dependencies

# pubspec.yaml
dependencies:
  flutter_easy_messages: ^0.3.0

Then run:

flutter pub get

Step 2: Use It!

import 'package:flutter_easy_messages/flutter_easy_messages.dart';

// Inside a widget with BuildContext
showAppToast(
  'Success!',
  context: context,
  messageType: MessageType.success,
);

That's it! 🎉 No complex setup or configuration needed to get started.

---

📖 Complete Usage Guide

🍞 Basic Toast Notifications

Using Message Types

// Success Toast - Green with checkmark
showAppToast(
  'Operation completed successfully!',
  context: context,
  messageType: MessageType.success,
);

// Error Toast - Red with error icon
showAppToast(
  'Something went wrong',
  context: context,
  messageType: MessageType.error,
);

// Info Toast - Blue with info icon
showAppToast(
  'Here is some useful information',
  context: context,
  messageType: MessageType.info,
);

// Warning Toast - Orange with warning icon
showAppToast(
  'Please be careful with this action',
  context: context,
  messageType: MessageType.warning,
);

Custom Styling

showAppToast(
  'Custom styled notification',
  context: context,
  backgroundColor: Colors.purple,
  duration: Duration(seconds: 3),
  position: MessagePosition.topCenter,
  borderRadius: 20,
  icon: Icon(Icons.favorite, color: Colors.white),
  fontSize: 16,
  fontWeight: FontWeight.bold,
  fontFamily: 'Roboto',
  maxLines: 2,
  offset: Offset(0, 10),
);

Position Your Toasts (9 Options)

// Top positions
MessagePosition.topLeft        // ↖️  Top-left corner
MessagePosition.topCenter      // ⬆️  Top center
MessagePosition.topRight       // ↗️  Top-right corner

// Center positions (vertically centered)
MessagePosition.centerLeft     // ⬅️  Center-left
MessagePosition.center         // ⭕ Center screen
MessagePosition.centerRight    // ➡️  Center-right

// Bottom positions
MessagePosition.bottomLeft     // ↙️  Bottom-left corner
MessagePosition.bottomCenter   // ⬇️  Bottom center (default)
MessagePosition.bottomRight    // ↘️  Bottom-right corner

Real example:

showAppToast(
  'Important notification',
  context: context,
  messageType: MessageType.info,
  position: MessagePosition.topRight,
  duration: Duration(seconds: 4),
);

Managing Multiple Messages

// Replace Mode (default) - Only one toast visible at a time
for (int i = 1; i <= 3; i++) {
  showAppToast(
    'Message $i',
    context: context,
    behavior: MessageBehavior.replace,
  );
}
// Result: Only 'Message 3' is shown

// Queue Mode - Messages shown sequentially
for (int i = 1; i <= 3; i++) {
  showAppToast(
    'Message $i',
    context: context,
    behavior: MessageBehavior.queue,
  );
}
// Result: All 3 messages shown in order

📋 Snackbars

// Simple snackbar notification
showAppSnackBar(
  'This is a snackbar message',
  context: context,
  messageType: MessageType.success,
);

// Snackbar with custom styling
showAppSnackBar(
  'Customized snackbar',
  context: context,
  messageType: MessageType.info,
  duration: Duration(seconds: 4),
  fontSize: 16,
  fontWeight: FontWeight.w600,
);

🌐 Context-Free Toasts (No BuildContext Needed!)

Perfect for showing toasts from services, utilities, and API calls without needing a BuildContext.

Setup (One-Time in main.dart)

import 'package:flutter_easy_messages/flutter_easy_messages.dart';

void main() {
  // Create a navigator key
  final navigatorKey = GlobalKey<NavigatorState>();

  // Set the navigator key FIRST
  EasyMessageConfig.setNavigatorKey(navigatorKey);

  // Optional: Configure global defaults
  EasyMessageConfig.configure(
    toastDuration: Duration(seconds: 2),
    borderRadius: 12,
    toastPosition: MessagePosition.bottomCenter,
    enablePulse: true,
  );

  runApp(MyApp(navigatorKey: navigatorKey));
}

class MyApp extends StatelessWidget {
  final GlobalKey<NavigatorState> navigatorKey;

  const MyApp({required this.navigatorKey, super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey,  // ← Pass the same key
      home: HomeScreen(),
    );
  }
}

Usage (Show Toasts Anywhere!)

// No context required!
showAppToast('Welcome back!', messageType: MessageType.success);

// In services
class AuthService {
  void logout() {
    showAppToast('Logged out successfully', messageType: MessageType.info);
  }
}

// In utility functions
void handleError(String error) {
  showAppToast(error, messageType: MessageType.error);
}

// In API calls
Future<void> fetchData() async {
  try {
    final data = await api.getData();
  } catch (e) {
    showAppToast('Failed to load data', messageType: MessageType.error);
  }
}

---

🎯 Advanced Features (Enterprise-Grade)

🔘 Action Buttons - Add Interactivity

Add retry, cancel, or custom action buttons to your toasts.

showAppToast(
  'Failed to upload document.pdf',
  context: context,
  messageType: MessageType.error,
  duration: Duration(seconds: 10),
  actions: [
    ToastAction(
      label: 'Retry',
      color: Colors.green,
      textColor: Colors.white,
      onPressed: () {
        retryUpload();
      },
    ),
    ToastAction(
      label: 'Cancel',
      color: Colors.red,
      textColor: Colors.white,
      onPressed: () {
        cancelOperation();
      },
    ),
  ],
);

📋 Error Details - Expandable Information

Display detailed error information that users can expand when needed.

showAppToast(
  '❌ API Request Failed',
  context: context,
  messageType: MessageType.error,
  duration: Duration(seconds: 8),
  errorDetails:
      'Status Code: 500\n'
      'Endpoint: /api/v1/upload\n'
      'Error: Internal Server Error\n'
      'Request ID: REQ-123456789',
);

User sees: ❌ API Request Failed [Show details]
Tapping reveals full error information.

⏳ Persistent Toasts - For Long Operations

Perfect for upload, download, or processing notifications that shouldn't auto-dismiss.

showAppToast(
  '⏳ Processing PDF file...',
  context: context,
  messageType: MessageType.info,
  isPersistent: true,        // Won't auto-dismiss
  dismissible: true,          // User can tap to close
  duration: Duration(seconds: 999),
  requestId: 'processing_pdf_001',
  onShown: () {
    // Called when toast appears
    startProcessing();
  },
  onDismissed: () {
    // Called when dismissed
    cleanup();
  },
);

// Later: Programmatically clear the toast
ToastManager.clearByRequestId('processing_pdf_001');

👆 Dismissible Toasts

Enable users to close notifications with a tap.

showAppToast(
  '👆 Tap anywhere on this toast to close it',
  context: context,
  messageType: MessageType.warning,
  dismissible: true,
  duration: Duration(seconds: 5),
);

🆔 Request ID Tracking

Track and manage toasts by request ID—ideal for API request correlation and preventing duplicates.

// Show toast for a specific request
showAppToast(
  'Processing order...',
  context: context,
  messageType: MessageType.info,
  isPersistent: true,
  requestId: 'order_checkout_001',
);

// Check how many toasts exist for this request
int count = ToastManager.getToastCountByRequestId('order_checkout_001');

// Clear all toasts for this request
await ToastManager.clearByRequestId('order_checkout_001');

// Clear everything
await ToastManager.clearAll();

📞 Lifecycle Callbacks

React to toast events—perfect for analytics, logging, and state management.

showAppToast(
  'Processing...',
  context: context,
  messageType: MessageType.info,
  isPersistent: true,
  onShown: () {
    // Called when toast appears on screen
    analytics.logEvent('notification_shown', {'message': 'Processing'});
    startTimer();
  },
  onDismissed: () {
    // Called when toast is dismissed
    analytics.logEvent('notification_dismissed', {'message': 'Processing'});
    stopTimer();
    refreshUI();
  },
);

📳 Haptic Feedback (Vibration)

Add a tactile pulse to your toasts and snackbars. Uses Flutter's built-in HapticFeedback, so there's no extra dependency and no Android VIBRATE permission required. On platforms without haptic hardware (web, desktop, simulators) the call is a silent no-op.

Quick Enable (per-call)

showAppToast(
  'Saved!',
  context: context,
  messageType: MessageType.success,
  enableVibration: true, // 👈 fires a haptic pulse
);

When enableVibration: true and no hapticType is given, the haptic is automatically derived from the MessageType:

MessageType	Haptic
error	HapticFeedbackType.heavyImpact
warning	HapticFeedbackType.mediumImpact
success	HapticFeedbackType.selectionClick
info / unspecified	HapticFeedbackType.lightImpact

Pick a Specific Haptic Variant

showAppToast(
  'Boom',
  context: context,
  enableVibration: true,
  hapticType: HapticFeedbackType.vibrate, // any of the 5 variants
);

Available variants: lightImpact, mediumImpact, heavyImpact, selectionClick, vibrate.

Enable Globally (so every message vibrates)

EasyMessageConfig.configure(
  enableVibration: true,
  // optional — fixes a single haptic variant for ALL messages.
  // omit to keep the smart MessageType-based mapping.
  // hapticType: HapticFeedbackType.mediumImpact,
);

Per-call enableVibration: false still wins, so you can opt individual messages out.

Snackbars Work the Same Way

showAppSnackBar(
  context,
  'Network error',
  messageType: MessageType.error,
  enableVibration: true,
);

⚠️ Important — showAppSnackBar vs buildAppSnackBar: Haptic feedback only fires from showAppSnackBar(...) (the imperative show-and-display helper). buildAppSnackBar(...) is a pure widget builder — it returns a SnackBar widget with no side effects, so it does not fire haptics. If you build the widget yourself and pass it to ScaffoldMessenger.showSnackBar(...), vibration will not trigger. Use showAppSnackBar whenever you want haptics (and to honor the global enableVibration config).

💡 Note: Haptics will not fire on the iOS Simulator or Android Emulator — test on a physical device. Users who have disabled system haptics will also see silent no-ops (expected).

---

⚙️ Global Configuration

Configure default behavior once in your main() function:

void main() {
  EasyMessageConfig.configure(
    toastDuration: Duration(seconds: 2),
    snackBarDuration: Duration(seconds: 3),
    toastEntryAnimationDuration: Duration(milliseconds: 400),
    toastExitAnimationDuration: Duration(milliseconds: 300),
    borderRadius: 12,
    toastPosition: MessagePosition.bottomCenter,
    toastBehavior: MessageBehavior.replace,
    enablePulse: true,
    enableVibration: false,        // global haptic toggle (default: false)
    // hapticType: HapticFeedbackType.lightImpact, // optional fixed variant
  );
  
  runApp(MyApp());
}

Animation Presets

Use built-in animation presets for consistent animations:

// Fast animations (200ms)
EasyMessageConfig.configure(
  toastEntryAnimationDuration: AnimationPresets.fast.entry,
  toastExitAnimationDuration: AnimationPresets.fast.exit,
);

// Normal animations (400ms) - default
EasyMessageConfig.configure(
  toastEntryAnimationDuration: AnimationPresets.normal.entry,
  toastExitAnimationDuration: AnimationPresets.normal.exit,
);

// Slow animations (600ms)
EasyMessageConfig.configure(
  toastEntryAnimationDuration: AnimationPresets.slow.entry,
  toastExitAnimationDuration: AnimationPresets.slow.exit,
);

---

💡 Real-World Examples

API Error Handling with Retry

Future<void> uploadFile(File file) async {
  try {
    showAppToast(
      '⏳ Uploading ${file.name}...',
      context: context,
      messageType: MessageType.info,
      isPersistent: true,
      requestId: 'upload_${file.hashCode}',
    );
    
    await api.uploadFile(file);
    await ToastManager.clearByRequestId('upload_${file.hashCode}');
    
    showAppToast(
      '✅ Upload complete!',
      context: context,
      messageType: MessageType.success,
    );
  } catch (e) {
    showAppToast(
      '❌ Upload failed',
      context: context,
      messageType: MessageType.error,
      duration: Duration(seconds: 10),
      actions: [
        ToastAction(
          label: 'Retry',
          color: Colors.green,
          onPressed: () => uploadFile(file),
        ),
      ],
    );
  }
}

Form Validation

void validateForm(Map<String, String> data) {
  if (data['email']?.isEmpty ?? true) {
    showAppToast(
      'Email is required',
      context: context,
      messageType: MessageType.error,
    );
    return;
  }
  submitForm(data);
}

---

🧠 Best Practices

✅ Do's

• ✓ Keep messages short (1-2 lines)
• ✓ Use appropriate message types
• ✓ Test on multiple screen sizes
• ✓ Use context-free toasts in services
• ✓ Use request IDs for long operations

❌ Don'ts

• ✗ Spam users with multiple toasts
• ✗ Keep toasts visible too long
• ✗ Use complex layouts
• ✗ Reconfigure globally too frequently

---

🆘 Troubleshooting

Issue	Solution
Toasts not showing	Set navigator key via EasyMessageConfig.setNavigatorKey()
Choppy animations	Try AnimationPresets.fast or run in release mode
Message stacking	Use MessageBehavior.replace (default)

---

📊 Quality & Testing

• ✅ 30/30 tests passing (100%)
• ✅ 0 code analysis issues
• ✅ Full null safety
• ✅ 90%+ documentation coverage
• ✅ Flutter 1.17.0+
• ✅ Dart 3.11.1+

---

📱 Responsive Design

Automatic layout adjustment for all screen sizes:

📱 Mobile      📱 Tablet       🖥️ Desktop
(<600px)       (600-1024px)    (>1024px)

All toasts adapt to screen width, height, and safe areas.

---

📁 Project Structure

flutter_easy_messages/
├── lib/
│   ├── flutter_easy_messages.dart
│   └── src/
│       ├── toast_helper.dart
│       ├── toast_manager.dart
│       ├── message_config.dart
│       ├── message_type.dart
│       ├── message_position.dart
│       ├── message_behavior.dart
│       └── ... (other modules)
├── test/
│   └── flutter_easy_messages_test.dart
├── example/
│   └── ... (demo app)
└── pubspec.yaml

---

🤝 Contributing

Contributions are welcome! Please:

1. Report issues on GitHub
2. Submit pull requests with improvements
3. Help improve documentation

---

📄 License

MIT License - see LICENSE file for details

---

📚 Resources

• Example App - Complete demo with 25+ examples
• GitHub - Source code
• Pub.dev - Package registry

---