cherry_toast_msgs 1.3.0

A beautiful, responsive toast notification package for Flutter with animated overlays, customizable themes, builder pattern API, queue management, and advanced interactive features.

Cherry Toast Messages

A beautiful, responsive toast notification package for Flutter with animated overlays, customizable themes, and advanced features. Perfect for displaying success, error, warning, and info messages with smooth animations and enhanced user experience.

✨ Features

• 🎨 Beautiful Design: Modern, clean toast notifications with smooth animations
• 📱 Responsive: Automatically adapts to different screen sizes and orientations
• 🎭 Multiple Themes: Pre-built themes for success, error, warning, and info messages with dark mode support
• ⚡ Customizable: Fully customizable colors, styles, animations, and behaviors
• 🚀 Easy to Use: Simple API with intuitive method names and fluent builder pattern
• 🎯 Accessible: Proper contrast ratios, touch targets, and screen reader support
• 🔄 Queue Management: Smart queue system to handle multiple toasts gracefully
• 👆 Interactive: Swipe-to-dismiss, tap-to-dismiss, and action button support
• 🎪 Advanced Animations: Multiple animation types (slide, fade, scale, bounce)
• 📍 Flexible Positioning: Top, bottom, center, and custom positioning
• 🎛️ Builder Pattern: Fluent API for complex toast configurations
• 🔧 Enhanced Error Handling: Robust validation and error recovery
• 📊 Lifecycle Callbacks: Complete control over toast lifecycle events

🚀 Getting Started

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  cherry_toast_msgs: ^1.3.0

Import

import 'package:cherry_toast_msgs/cherry_toast_msgs.dart';

📖 Usage

Basic Toast Types

Success Toast

CherryToastMsgs.showSuccessToast(
  context: context,
  title: "Success!",
  description: "Your action was completed successfully.",
);

Error Toast

CherryToastMsgs.showErrorToast(
  context,
  "Error!",
  "Something went wrong. Please try again.",
);

Warning Toast

CherryToastMsgs.showWarningToast(
  context,
  "Warning!",
  "Please check your input before proceeding.",
);

Info Toast

CherryToastMsgs.showInfoToast(
  context,
  "Information",
  "Here's some useful information for you.",
);

🏗️ Builder Pattern (New!)

The fluent builder pattern provides a more flexible and readable way to create toasts:

// Simple builder usage
CherryToastMsgs.builder()
    .context(context)
    .title("Builder Pattern")
    .description("This toast was created using the fluent builder API")
    .success()
    .show();

// Advanced builder usage
CherryToastMsgs.builder()
    .context(context)
    .title("Advanced Toast")
    .description("With multiple features enabled")
    .error()
    .darkMode()
    .hapticFeedback()
    .duration(Duration(seconds: 5))
    .position(ToastPosition.center)
    .actions([
      TextButton(
        onPressed: () => print('Action pressed'),
        child: Text('Action'),
      ),
    ])
    .callbacks(ToastCallbacks(
      onShow: () => print('Toast shown'),
      onDismiss: () => print('Toast dismissed'),
    ))
    .show();

🎨 Theme System (New!)

Predefined Themes

// Light themes
CherryToastMsgs.builder()
    .context(context)
    .title("Themed Toast")
    .description("Using predefined theme")
    .theme(CherryToastTheme.success)
    .show();

// Dark themes
CherryToastMsgs.builder()
    .context(context)
    .title("Dark Theme")
    .description("Using dark theme variant")
    .theme(CherryToastTheme.successDark)
    .show();

// Or use the convenience method
CherryToastMsgs.builder()
    .context(context)
    .title("Auto Dark Theme")
    .description("Automatically uses dark variant")
    .success()
    .darkMode()
    .show();

Custom Themes

final customTheme = CherryToastTheme.success.copyWith(
  backgroundColor: Colors.purple.shade50,
  borderColor: Colors.purple.shade200,
  iconBackground: Colors.purple,
);

CherryToastMsgs.builder()
    .context(context)
    .title("Custom Theme")
    .description("Using custom theme colors")
    .theme(customTheme)
    .show();

🎪 Animation Types (New!)

// Slide animation (default)
CherryToastMsgs.builder()
    .context(context)
    .title("Slide Animation")
    .description("Slides in from the edge")
    .success()
    .animation(CherryToastAnimation.slide)
    .show();

// Fade animation
CherryToastMsgs.builder()
    .context(context)
    .title("Fade Animation")
    .description("Fades in smoothly")
    .info()
    .animation(CherryToastAnimation.fade)
    .show();

// Scale animation
CherryToastMsgs.builder()
    .context(context)
    .title("Scale Animation")
    .description("Scales up from center")
    .warning()
    .animation(CherryToastAnimation.scale)
    .show();

// Bounce animation
CherryToastMsgs.builder()
    .context(context)
    .title("Bounce Animation")
    .description("Bounces in with elastic effect")
    .error()
    .animation(CherryToastAnimation.bounce)
    .show();

📍 Positioning

// Top position (default)
CherryToastMsgs.showSuccessToast(
  context: context,
  title: "Top Toast",
  description: "Appears at the top",
  position: ToastPosition.top,
);

// Bottom position
CherryToastMsgs.showErrorToast(
  context,
  "Bottom Toast",
  "Appears at the bottom",
  position: ToastPosition.bottom,
);

// Center position
CherryToastMsgs.showInfoToast(
  context,
  "Center Toast",
  "Appears in the center",
  position: ToastPosition.center,
);

// Custom position with offset
CherryToastMsgs.showWarningToast(
  context,
  "Custom Position",
  "Custom offset from top",
  position: ToastPosition.custom,
  topOffset: 100.0,
);

🎛️ Configuration Options (New!)

// Quick configurations
CherryToastMsgs.builder()
    .context(context)
    .title("Quick Toast")
    .description("Short duration, fast animation")
    .success()
    .quick() // 2 seconds, fast animation
    .show();

CherryToastMsgs.builder()
    .context(context)
    .title("Persistent Toast")
    .description("Longer duration, always shows close button")
    .warning()
    .persistent() // 8 seconds, always closeable
    .show();

// Custom configuration
final customConfig = CherryToastConfig(
  duration: Duration(seconds: 5),
  animationType: CherryToastAnimation.bounce,
  enableHapticFeedback: true,
  dismissOnTap: true,
  showCloseButton: true,
);

CherryToastMsgs.showSuccessToast(
  context: context,
  title: "Custom Config",
  description: "Using custom configuration",
  config: customConfig,
);

👆 Interactive Features (New!)

Action Buttons

CherryToastMsgs.builder()
    .context(context)
    .title("Interactive Toast")
    .description("Toast with action buttons")
    .warning()
    .actions([
      TextButton(
        onPressed: () => print('Retry pressed'),
        child: Text('Retry'),
      ),
      TextButton(
        onPressed: () => print('Cancel pressed'),
        child: Text('Cancel'),
      ),
    ])
    .show();

Lifecycle Callbacks

CherryToastMsgs.builder()
    .context(context)
    .title("Callback Toast")
    .description("With lifecycle callbacks")
    .info()
    .callbacks(ToastCallbacks(
      onShow: () => print('Toast appeared'),
      onDismiss: () => print('Toast will disappear'),
      onDismissed: (reason) => print('Toast dismissed: $reason'),
      onTap: () => print('Toast was tapped'),
    ))
    .show();

Haptic Feedback

CherryToastMsgs.builder()
    .context(context)
    .title("Haptic Toast")
    .description("Provides haptic feedback")
    .success()
    .hapticFeedback()
    .show();

🔄 Queue Management (New!)

// Multiple toasts are automatically queued
for (int i = 0; i < 5; i++) {
  CherryToastMsgs.builder()
      .context(context)
      .title("Toast ${i + 1}")
      .description("Queued toast message")
      .info()
      .show();
}

// Clear the queue
CherryToastMsgs.clearQueue();

// Check queue size
int queueSize = CherryToastMsgs.queueSize;
print('Current queue size: $queueSize');

🏷️ Static Info Container

For static information displays, use the StaticInfoContainer:

StaticInfoContainer(
  message: "This is a static information container",
  icon: Icons.info_outline,
  backgroundColor: Colors.blue.shade50,
  borderColor: Colors.blue.shade200,
  iconColor: Colors.blue.shade600,
  textColor: Colors.blue.shade700,
)

🎨 Custom Styling

CherryToastMsgs.showAnimatedToast(
  context: context,
  title: "Custom Styled Toast",
  description: "Fully customized appearance",
  icon: Icons.star,
  iconColor: Colors.white,
  iconBackground: Colors.purple,
  backgroundColor: Colors.purple.shade50,
  borderColor: Colors.purple.shade200,
  titleStyle: TextStyle(
    color: Colors.purple.shade800,
    fontWeight: FontWeight.bold,
    fontSize: 18,
  ),
  descriptionStyle: TextStyle(
    color: Colors.purple.shade600,
    fontSize: 16,
  ),
  borderRadius: 16,
  borderWidth: 2,
  duration: Duration(seconds: 5),
  elevation: 12,
  width: 300,
  height: 120,
  animationType: CherryToastAnimation.bounce,
  dismissOnTap: true,
  showCloseButton: true,
);

📚 API Reference

CherryToastMsgs

Static Methods

• showSuccessToast() - Shows a green success toast
• showErrorToast() - Shows a red error toast
• showWarningToast() - Shows a yellow warning toast
• showInfoToast() - Shows a blue info toast
• showAnimatedToast() - Method for custom toasts with full customization
• builder() - Creates a new toast builder instance
• success(), error(), warning(), info() - Quick builder methods
• clearQueue() - Clears all queued toasts
• queueSize - Gets current queue size

Enhanced Parameters

All toast methods now support:

• config - Toast configuration object
• enableHapticFeedback - Enable haptic feedback
• callbacks - Lifecycle callbacks
• Enhanced positioning and styling options

CherryToastBuilder (New!)

Fluent API for building complex toasts:

Configuration Methods

• context(BuildContext) - Set build context
• title(String) - Set title text
• description(String) - Set description text
• theme(CherryToastTheme) - Set predefined theme
• config(CherryToastConfig) - Set configuration
• callbacks(ToastCallbacks) - Set lifecycle callbacks

Styling Methods

• darkMode([bool]) - Enable/disable dark mode
• width(double) - Set custom width
• height(double) - Set custom height
• animation(CherryToastAnimation) - Set animation type

Positioning Methods

• position(ToastPosition) - Set position
• top([double]) - Position at top with optional offset
• bottom([double]) - Position at bottom with optional offset
• center() - Position at center
• customPosition(double) - Custom positioning with offset

Behavior Methods

• duration(Duration) - Set display duration
• hapticFeedback([bool]) - Enable haptic feedback
• persistent() - Use persistent configuration
• quick() - Use quick configuration

Content Methods

• actions(List<Widget>) - Add action buttons
• customContent(Widget) - Set custom content widget

Quick Theme Methods

• success() - Apply success theme
• error() - Apply error theme
• warning() - Apply warning theme
• info() - Apply info theme

Build Method

• show() - Build and display the toast

CherryToastTheme (New!)

Predefined theme system:

Light Themes

• CherryToastTheme.success - Green success theme
• CherryToastTheme.error - Red error theme
• CherryToastTheme.warning - Orange warning theme
• CherryToastTheme.info - Blue info theme

Dark Themes

• CherryToastTheme.successDark - Dark success theme
• CherryToastTheme.errorDark - Dark error theme
• CherryToastTheme.warningDark - Dark warning theme
• CherryToastTheme.infoDark - Dark info theme

Methods

• getTheme(String, {bool isDark}) - Get theme by type
• copyWith({...}) - Create custom theme variant

CherryToastConfig (New!)

Configuration class for toast behavior:

Properties

• duration - Display duration (default: 3 seconds)
• animationType - Animation type (default: slideAndFade)
• animationDuration - Animation duration (default: 350ms)
• enableHapticFeedback - Enable haptic feedback (default: false)
• enableSoundFeedback - Enable sound feedback (default: false)
• dismissOnTap - Dismiss on tap (default: true)
• showCloseButton - Show close button (default: true)
• borderRadius, borderWidth, elevation - Visual properties
• shadowColor, padding, margin - Layout properties

Predefined Configurations

• CherryToastConfig.defaultConfig - Default settings
• CherryToastConfig.quick - Quick toast (2 seconds, fast animation)
• CherryToastConfig.persistent - Persistent toast (8 seconds, always closeable)

CherryToastAnimation (New!)

Animation types:

• CherryToastAnimation.slide - Slide from edge
• CherryToastAnimation.fade - Fade in/out
• CherryToastAnimation.scale - Scale from center
• CherryToastAnimation.bounce - Bounce with elastic effect
• CherryToastAnimation.slideAndFade - Combined slide and fade (default)

ToastCallbacks (New!)

Lifecycle callback functions:

• onShow - Called when toast appears
• onDismiss - Called when toast starts dismissing
• onDismissed(ToastDismissReason) - Called when toast is fully dismissed
• onTap - Called when toast is tapped

ToastDismissReason (New!)

Dismissal reasons:

• ToastDismissReason.timeout - Auto-dismissed after duration
• ToastDismissReason.userDismiss - User clicked close button
• ToastDismissReason.swipe - User swiped to dismiss
• ToastDismissReason.tap - User tapped to dismiss
• ToastDismissReason.programmatic - Dismissed programmatically

ToastPosition

Position options:

• ToastPosition.top - Top of screen (default)
• ToastPosition.bottom - Bottom of screen
• ToastPosition.center - Center of screen
• ToastPosition.custom - Custom position with offset

StaticInfoContainer

Static information display widget:

Properties

• message - Text message to display
• icon - Icon to display (default: Icons.info_outline)
• backgroundColor, borderColor, iconColor, textColor - Colors
• borderRadius, padding, iconSize, fontSize - Styling
• width, height - Custom dimensions

🔧 Migration Guide

From v1.2.x to v1.3.x

Breaking Changes

• StaticeInfoContainer renamed to StaticInfoContainer

New Features

• Builder pattern API
• Theme system with dark mode support
• Enhanced animation types
• Queue management system
• Lifecycle callbacks
• Haptic feedback support
• Action buttons
• Enhanced error handling

Migration Steps

1. Update widget name:

// Old
StaticeInfoContainer(message: "Info")

// New
StaticInfoContainer(message: "Info")

2. Consider using builder pattern for complex toasts:

// Old
CherryToastMsgs.showAnimatedToast(
  context: context,
  title: "Title",
  description: "Description",
  icon: Icons.success,
  // ... many parameters
);

// New (recommended)
CherryToastMsgs.builder()
    .context(context)
    .title("Title")
    .description("Description")
    .success()
    .show();

3. Use new theme system:

// New theme-based approach
CherryToastMsgs.builder()
    .context(context)
    .title("Themed Toast")
    .description("Using predefined theme")
    .success()
    .darkMode() // Automatically uses dark variant
    .show();

🧪 Testing

The package includes comprehensive tests for all components:

flutter test

Test coverage includes:

• Widget creation and rendering
• Theme system functionality
• Configuration validation
• Queue management
• Animation systems
• Error handling

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (flutter test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📖 Improving documentation
• 🔄 Sharing with the community

📞 Contact

• GitHub: Abdullah-T3/cherry_toast_msgs
• Issues: Report Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by Abdullah Ahmed