SwiftAlert is a lightweight, customizable Flutter package for displaying beautiful top-of-screen notification alerts. It supports multiple notification types (success, error, info, warning), smooth animations, and easy integration with any Flutter app.

Features

• Show animated notification banners at the top of the screen
• Support for success, error, info, and warning types
• Customizable colors and icons per notification type
• Dismiss on tap or swipe
• No context required - Initialize once and use anywhere in your app
• Simple API: just call SwiftAlert.show()
• Works seamlessly with overlays
• Backward compatible with context-based API

Screenshots

Error Notification:

Success Notification:

Getting started

Installation

From pub.dev (recommended):

Add this to your pubspec.yaml:

dependencies:
  swift_alert: ^2.0.0 # Check pub.dev for the latest version

Then run:

flutter pub get

From GitHub (development):

dependencies:
  swift_alert:
    git:
      url: https://github.com/Collins-01/Swift-Alert.git

Then run:

flutter pub get

Usage

New API (v2.0.0+) - No Context Required

Step 1: Initialize SwiftAlert at app startup

Create a global navigator key and initialize SwiftAlert in your main() function:

import 'package:flutter/material.dart';
import 'package:swift_alert/swift_alert.dart';

// Create a global navigator key
final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

void main() {
  // Initialize SwiftAlert with the navigator key
  SwiftAlert.initialize(navigatorKey: navigatorKey);
  runApp(const MyApp());
}

Step 2: Pass the navigator key to MaterialApp

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      navigatorKey: navigatorKey, // Pass the navigator key here
      home: const HomePage(),
    );
  }
}

Step 3: Show notifications anywhere without context

Now you can show notifications from anywhere in your app without needing a BuildContext:

// In your business logic, state management, or anywhere else
SwiftAlert.show(
  message: 'Profile updated successfully!',
  type: NotificationType.success,
);

// With custom duration
SwiftAlert.show(
  message: 'Custom message',
  duration: Duration(seconds: 6),
  type: NotificationType.warning,
);

Notification Types

• NotificationType.success (green) - For successful operations
• NotificationType.error (red) - For errors and failures
• NotificationType.info (blue) - For informational messages
• NotificationType.warning (yellow) - For warnings and cautions

Legacy API (v1.x) - With Context

The old context-based API is still supported for backward compatibility:

import 'package:swift_alert/swift_alert.dart';

// In your widget (e.g., after a button press):
SwiftAlert.display(
  context,
  message: 'Profile updated successfully!',
  type: NotificationType.success,
);

Note: The display() method is deprecated and will be removed in a future version. Please migrate to the new show() API.

Dismissing

Notifications can be dismissed by:

• Tapping anywhere on the notification
• Swiping up
• Clicking the close button
• Automatically after the duration expires (default: 4 seconds)

Advanced Usage

Using in State Management

Since SwiftAlert doesn't require context after initialization, you can easily use it in your state management layer:

// In your BLoC, Provider, Riverpod, etc.
class UserRepository {
  Future<void> updateProfile(UserData data) async {
    try {
      await api.updateUser(data);
      SwiftAlert.show(
        message: 'Profile updated successfully!',
        type: NotificationType.success,
      );
    } catch (e) {
      SwiftAlert.show(
        message: 'Failed to update profile: $e',
        type: NotificationType.error,
      );
    }
  }
}

Using in Services

class AuthService {
  Future<void> logout() async {
    await _clearSession();
    SwiftAlert.show(
      message: 'You have been logged out',
      type: NotificationType.info,
    );
  }
}

API Reference

SwiftAlert.initialize()

Initializes SwiftAlert with a navigator key. Must be called once at app startup.

Parameters:

• navigatorKey (required): GlobalKey<NavigatorState> - The navigator key used by your MaterialApp

SwiftAlert.show()

Displays a notification without requiring context.

Parameters:

• message (required): String - The message to display
• type (optional): NotificationType - The type of notification (default: NotificationType.error)
• duration (optional): Duration - How long to display the notification (default: 4 seconds)

SwiftAlert.display() [Deprecated]

Legacy method that requires a BuildContext. Use show() instead.

See the Dart API docs for full details on all classes and methods.

Troubleshooting / FAQ

"SwiftAlert has not been initialized" error

Make sure you call SwiftAlert.initialize(navigatorKey: yourKey) before using SwiftAlert.show().

"Navigator context is not available" error

Ensure you pass the same navigator key to both SwiftAlert.initialize() and your MaterialApp's navigatorKey parameter.

Alert doesn't show

• Verify that SwiftAlert is properly initialized
• Check that your MaterialApp is using the correct navigator key
• Ensure you're not calling show() before the MaterialApp is built

Multiple notifications

Only one notification is shown at a time. Calling SwiftAlert.show() will replace any currently displayed alert.

Custom styling

For custom icons, colors, or layouts, you can extend the NotificationType enum or create your own notification widget based on OverlayNotification.

Contributing & Support

For more information, see the GitHub repository.

Contributions are welcome! Please open issues or pull requests for bugs, features, or improvements.

For questions or help, open an issue on GitHub or reach out to the maintainer.