BotToast Documentation

In version 3.0 and above, the initialization logic was reimplemented to be simpler and no longer depend on the Navigator.

Old 2.x.x method:

BotToastInit(
  child: MaterialApp(
      title: 'BotToast Demo',
      navigatorObservers: [BotToastNavigatorObserver()],
      home: XxxxPage(),
  )
);

New 3.x.x/4.x.x method:

MaterialApp(
      title: 'BotToast Demo',
      builder: BotToastInit(), 
      navigatorObservers: [BotToastNavigatorObserver()],
      home: XxxxPage(),
)

To run the provided example project to see BotToast in action, navigate to the example directory, initialize the Flutter project, and run it using the Flutter CLI.

cd example
flutter create .
flutter run

To use BotToast, you must initialize it in your MaterialApp using BotToastInit in the builder property and register BotToastNavigatorObserver in navigatorObservers.

Warning: Do not arbitrarily change the position of the BotToastInit function call within the builder.

MaterialApp(
      title: 'BotToast Demo',
      builder: BotToastInit(), // 1. Call BotToastInit
      navigatorObservers: [BotToastNavigatorObserver()], // 2. Register route observer
      home: XxxxPage(),
  )

Add bot_toast to your pubspec.yaml dependencies. Ensure you use a version compatible with null safety (e.g., ^4.1.0).

dependencies:
    bot_toast: ^4.1.0 #null safety

When using ToastBuilder (via showCustomNotification or showCustomText) to generate widgets, ensure the generated widget's background does not absorb click events.

Widgets like Scaffold or Material occupy the entire parent space and absorb events by default, even if they are transparent. If your widget absorbs events, features like allowClick (clicking through the toast to the background) will fail.

Solution: If you must use a widget that absorbs events, wrap it in an IgnorePointer widget.

To enable toast functionality in your Flutter application, you must wrap your application's root widget (usually inside MaterialApp) with the BotToastManager widget. This widget manages the overlay stack where all toasts and notifications will be rendered.

void main() {
  runApp(
    BotToastManager(
      child: MaterialApp(
        // ... your app configuration
      ),
    ),
  );
}

If your Flutter project uses multiple Navigator instances, you must add BotToastNavigatorObserver to the navigatorObservers list of each Navigator. This ensures that toasts are correctly managed and visible during navigation transitions across different parts of your app.

To use it, initialize your app with BotToastInit and include the observer in your MaterialApp (or any Navigator):

BotToastInit(
  child: MaterialApp(
    title: 'Xxxx Demo',
    navigatorObservers: [BotToastNavigatorObserver()],
    home: XxxxPage(),
  ),
);

Multiple Navigators

If your project uses multiple Navigator widgets, you must add BotToastNavigatorObserver to the Navigator.observers list of each navigator to ensure all features work correctly.

Widget Backgrounds and Click Events

When using ToastBuilder to generate custom widgets, ensure the generated widget's background does not intercept click events. Widgets like Scaffold or Material default to occupying the entire parent space and will absorb touch events (even if they are transparent).

Use showAttachedWidget to display a widget at a specific position on the screen relative to a target. This is useful for context-specific notifications or attachments.

// Popup an attachments toast
var cancel = BotToast.showAttachedWidget(
    attachedBuilder: (_) => Card(
          child: Padding(
            padding: const EdgeInsets.all(8.0),
            child: Icon(
              Icons.favorite,
              color: Colors.redAccent,
            ),
          ),
        ),
    duration: Duration(seconds: 2),
    target: Offset(520, 520));
// ...
cancel(); // close

Use showAttachedWidget to display a widget at a specific position on the screen using an Offset.

// Show a positioned toast
var cancel = BotToast.showAttachedWidget(
    attachedBuilder: (_) => Card(
          child: Padding(
            padding: const EdgeInsets.all(8.0),
            child: Icon(
              Icons.favorite,
              color: Colors.redAccent,
            ),
          ),
        ),
    duration: Duration(seconds: 2),
    target: Offset(520, 520));
// ...
cancel(); // Close