queued_toast 1.0.0

Overlay toasts for Flutter that queue per screen position, de-duplicate identical messages, stack up to five at a time and fade in and out.

queued_toast

Overlay toasts for Flutter that queue per screen position, de-duplicate identical messages, stack up to five at a time, and slide/fade in and out — all without a BuildContext at the call site.

Queueing · the five styles · the three positions · dark mode

Features

• Three positions — top, center and bottom, each with its own independent queue.
• Adjustable edge offset — offset sets how far a top or bottom toast sits from its edge, on top of the margin and safe area.
• Automatic queueing — at most five toasts are visible per position; the rest wait their turn.
• De-duplication — a toast whose title and description match one already shown or queued is dropped.
• Five styles — error, success, info, warning and minimal, each with a default icon and colour.
• Light/dark theming — ToastTheme resolves background, text and icon colours from the ambient Theme brightness.
• Fully overridable per call — colours, icon, radius, elevation, padding, margin, max width, offset, and both durations.
• Readable by default — high-contrast surfaces, a hairline border, a blurred backdrop, and tuned type sizing, weight, tracking and line height.

Install

dependencies:
  queued_toast: ^1.0.0

Usage

Toasts are rendered into the navigator's overlay, so the package needs your root navigator key once at startup:

import 'package:queued_toast/queued_toast.dart';

final navigatorKey = GlobalKey<NavigatorState>();

void main() {
  Toast.init(navigatorKey: navigatorKey);
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) =>
      MaterialApp(navigatorKey: navigatorKey, home: const HomePage());
}

Then show a toast from anywhere — a bloc, a repository, a callback:

Toast.show(
  title: 'Order filled',
  description: '0.5 BTC at 64,120 USDT',
  style: ToastStyle.success,
  position: ToastPosition.top,
);

Toast.show throws if Toast.init has not been called.

Options

Parameter	Default	Description
description	required	Body text.
title	null	Optional bold line above the description.
style	ToastStyle.minimal	Picks the default background colour and icon.
position	ToastPosition.bottom	Which queue the toast joins.
duration	2 s	How long the toast stays before reversing out.
animationDuration	300 ms	Slide + fade in/out length.
offset	30% of screen height	Extra distance from the top or bottom edge, in logical pixels. Ignored at center.
icon	style default	Replaces the built-in icon entirely.
iconSize	20	Size of the default icon.
bgColor / textColor	theme	Per-call colour overrides.
borderRadius	14	Corner radius of the card.
elevation	6	Material elevation.
maxWidth	420	Widest the card grows before text wraps.
padding	EdgeInsets.symmetric(horizontal: 16, vertical: 12)	Inside the card.
margin	EdgeInsets.all(12)	Between the card and the screen edge.

The offset is measured on top of margin and the safe area, and only the offset of the oldest toast still on screen at a position is applied — one position is one stack:

Toast.show(
  description: 'Pinned 24px above the bottom edge',
  position: ToastPosition.bottom,
  offset: 24,
);

Theming

Pass a ToastTheme to Toast.init to restyle every toast at once:

Toast.init(
  navigatorKey: navigatorKey,
  theme: ToastTheme(
    lightBackgroundColors: {ToastStyle.success: Colors.teal.shade700},
    darkBackgroundColors: {ToastStyle.success: Colors.teal.shade900},
    fontFamily: 'Inter',
    titleFontSize: 15,
    titleFontWeight: FontWeight.w600,
    descriptionFontSize: 13.5,
    descriptionOpacity: 0.88,
  ),
);

Typography is tunable beyond size: titleFontWeight, titleLetterSpacing, titleHeight, descriptionFontWeight, descriptionLetterSpacing, descriptionHeight and descriptionOpacity all have defaults tuned for small overlay text, and fontFamily swaps the face for both lines. lightBorderColor and darkBorderColor control the hairline around the card.

ToastTheme.copyWith merges background-colour overrides into the existing maps rather than replacing them, so you can tweak a single style and keep the rest.

Regenerating the screenshots

The images above are rendered headlessly, so they stay in step with the code:

flutter test tool/generate_media.dart --update-goldens && python3 tool/assemble_gif.py

The first command writes the stills into screenshots/ and the GIF's frames into build/gif_frames/; the second encodes those frames into screenshots/queue.gif (needs Pillow). Neither tool/ nor build/ ships with the package.

License

MIT — see LICENSE.