native_toast_pro 1.0.0

A production-ready Flutter plugin providing unified native toast experience across Android and iOS platforms with clean API and robust error handling.

Native Toast Pro

A production-ready Flutter plugin that provides a unified native toast experience across Android and iOS platforms with clean API and robust error handling.

Features

• 🚀 Native Performance: Uses real Android Toast API and custom UIView implementation for iOS
• 🛡️ Error Handling: Comprehensive error handling with PlatformException wrapping
• ⚡ Rate Limiting: Built-in rate limiting (500ms) to prevent toast spam
• 🔧 Clean Architecture: Service-based design with proper separation of concerns
• 📱 Cross-Platform: Identical API across Android and iOS
• ✅ Null Safe: Full null safety support with input validation
• 🧪 Well Tested: Comprehensive unit and integration tests

Platform Behavior

Android

• Uses the native Android Toast.makeText() API
• Leverages applicationContext to prevent memory leaks
• Standard Android toast duration (LENGTH_SHORT)

iOS

• Custom UIView-based toast implementation (iOS has no system toast API)
• Native fade in/out animations
• Auto-dismisses after 2.5 seconds
• Positioned at bottom with safe area margins

Installation

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

dependencies:
  native_toast_pro: ^1.0.0

Then run:

flutter pub get

Usage

Basic Usage

import 'package:native_toast_pro/native_toast_pro.dart';

// Show a simple toast
await NativeToastPro.show('Hello Native Toast!');

Advanced Usage

import 'package:native_toast_pro/native_toast_pro.dart';

try {
  // Show toast with error handling
  await NativeToastPro.show('This is a toast message!');
  
  // Show multiple toasts without rate limiting (use with caution)
  await NativeToastPro.showWithoutRateLimit('First toast');
  await NativeToastPro.showWithoutRateLimit('Second toast');
  
  // Check if platform supports native toasts
  bool isSupported = await NativeToastPro.isSupported;
  print('Toast support: $isSupported');
  
} on ArgumentError catch (e) {
  print('Invalid argument: ${e.message}');
} on PlatformException catch (e) {
  print('Platform error: ${e.message}');
}

API Reference

Static Methods

NativeToastPro.show(String message)

Shows a native toast message with rate limiting.

Parameters:

• message (String): The message to display (must be non-empty)

Throws:

• ArgumentError: If message is null or empty
• PlatformException: If toast cannot be displayed

NativeToastPro.showWithoutRateLimit(String message)

Shows a toast message without rate limiting. Use with caution.

Parameters:

• message (String): The message to display (must be non-empty)

Throws:

• ArgumentError: If message is null or empty
• PlatformException: If toast cannot be displayed

Future<bool> NativeToastPro.isSupported

Checks if the current platform supports native toast functionality.

Returns:

• bool: True if supported, false otherwise

Error Handling

The plugin provides comprehensive error handling:

try {
  await NativeToastPro.show('Hello!');
} on ArgumentError catch (e) {
  // Handle invalid input (empty/null message)
  print('Input error: ${e.message}');
} on PlatformException catch (e) {
  // Handle platform-specific errors
  print('Platform error: ${e.code} - ${e.message}');
} catch (e) {
  // Handle unexpected errors
  print('Unexpected error: $e');
}

Rate Limiting

To prevent toast spam and improve user experience, the plugin includes rate limiting:

• Default rate limit: 500ms between toasts
• Bypass option: Use showWithoutRateLimit() if needed
• Silent handling: Rate-limited calls are silently ignored

Example App

See the /example directory for a complete Flutter app demonstrating all features:

• Basic toast functionality
• Error handling examples
• Rate limiting demonstration
• Platform information display

Run the example:

cd example
flutter run

Architecture

The plugin follows clean architecture principles:

lib/
├── native_toast_pro.dart              # Main API layer
├── native_toast_pro_platform_interface.dart  # Platform abstraction
└── native_toast_pro_method_channel.dart      # Method channel implementation

android/
└── src/main/kotlin/com/example/native_toast_pro/
    ├── NativeToastProPlugin.kt         # Main plugin class
    └── ToastHandler.kt                 # Business logic

ios/
└── Classes/
    └── NativeToastProPlugin.swift      # iOS implementation with ToastView

Limitations

Android

• Message length limited to 200 characters (practical limit)
• Standard Android toast styling (no custom colors/fonts)

iOS

• Custom implementation (not system toast)
• Fixed styling (black background, white text)
• 2.5 second display duration (not configurable)

Future Improvements

• ❌ Customizable toast duration
• ❌ Custom styling options (colors, fonts)
• ❌ Toast positioning options
• ❌ Dismiss callbacks
• ❌ Toast queue management
• ❌ Web platform support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Support

If you have any questions or issues, please:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include platform, Flutter version, and error logs

Changelog

See CHANGELOG.md for a list of changes and version history.

Getting Started

This project is a starting point for a Flutter plug-in package, a specialized package that includes platform-specific implementation code for Android and/or iOS.

For help getting started with Flutter development, view the online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.