🧈 butter_toast #

Toasts that feel smooth as butter.

Pill and Sonner-style card toasts for Flutter, with spring animations, seven positions that each move their own way, promise toasts, and swipe to dismiss. No BuildContext needed.

📚 Contents #

• Why butter_toast?
• See it move
• Quick start
• Showing toasts: show and the shortcuts
• All parameters
• Updating and dismissing a toast
• Promise toasts
• Positions
• Pill or card
• Swipe to dismiss
• Repeated taps and tags
• Icons and the app icon
• Theming: app-wide and per toast
• Dialogs and bottom sheets
• Long text, keyboard and safe area
• Fully custom toasts
• Coming from fluttertoast?
• Platforms

✨ Why butter_toast? #

fluttertoast shows the native Android toast. Since Android 11 the system cuts that toast to two lines, ignores your position and blocks custom layouts. Most Flutter alternatives fix that by drawing a wide snackbar. butter_toast draws a real toast: small, light, and out of your way.

🎬 See it move #

Swipe any toast, any direction	Corners slide in from the side	Promise: loading → success

Pill	Card	Long message

🚀 Quick start #

1. Add the package

dependencies:
  butter_toast: ^0.1.0

2. Add the toast layer to your app, once

import 'package:butter_toast/butter_toast.dart';

MaterialApp(
  builder: ButterToast.init(), // 👈 that's it
  home: const HomePage(),
);

ButterToast.init() puts the toasts above the Navigator, so they show on every screen, dialog and bottom sheet. Already using builder? Chain them:

builder: (context, child) => ButterToast.init()(context, MyWrapper(child)),

3. Toast from anywhere

ButterToast.show('Copied to clipboard');

No BuildContext, so it works from widgets, blocs, services and interceptors alike.

🍞 Showing toasts: show and the shortcuts #

There's one method that does everything, ButterToast.show. You choose what the toast is about with the type enum:

ButterToast.show('Event created', type: ButterToastType.success);
ButterToast.show("Couldn't send", type: ButterToastType.error);

For everyday code there are shortcuts that fill in the type for you. They take the same parameters as show, so use whichever reads better:

Which one should I use?

• Use a shortcut when you know the type while writing the code. It's shorter and reads like a sentence:

  ButterToast.success('Profile saved', description: 'Changes are live.');
  

• Use show with type when the type comes from data, like an API result, so you don't need an if for every case:

  ButterToast.show(
    result.message,
    type: result.ok ? ButterToastType.success : ButterToastType.error,
  );
  

Both return a ButterToastHandle you can use to update or dismiss the toast later.

🧾 All parameters #

Every parameter except the message is optional. Anything you leave out comes from the theme.

ButterToast.show(
  'Payment received',                        // main text (the title on a card)
  description: '₹1,200 from Sam',            // quieter second line
  type: ButterToastType.success,             // icon and its colour
  style: ButterToastStyle.card,              // pill or card
  position: ButterToastPosition.topCenter,   // one of 7 positions
  duration: const Duration(seconds: 6),      // Duration.zero = until dismissed
  icon: const Icon(Icons.payments),          // replaces the type icon
  showIcon: true,                            // false hides the icon
  onTap: () => openPayments(),               // called when tapped
  dismissible: true,                         // false turns off swiping
  tag: 'payment',                            // same tag updates this toast
  theme: const ButterToastTheme(...),        // style for this toast only
);

🔄 Updating and dismissing a toast #

Every call returns a ButterToastHandle:

final toast = ButterToast.loading('Syncing…');

// later
toast.update(message: 'All synced', type: ButterToastType.success);
// or
toast.dismiss();

toast.isActive; // false once it has left the screen

update morphs the same toast smoothly, and restarts its timer when it turns from loading into anything else. To clear the screen, call ButterToast.dismissAll().

⏳ Promise toasts #

One toast follows your future from start to finish:

final photos = await ButterToast.promise(
  api.uploadPhotos(),
  loading: 'Uploading photos…',
  success: (count) => '$count photos uploaded',
  error: (e) => "Couldn't upload your photos",
);

It returns the future's result. If the future fails, the error toast shows and the error is rethrown, so your own try/catch still works. promise also takes style, position, tag and theme.

🎯 Positions #

ButterToast.show('Hi', position: ButterToastPosition.topRight);

A toast keeps its position for its whole life, even if the default changes while it's on screen.

🃏 Pill or card #

ButterToast.show('Saved', style: ButterToastStyle.pill);
ButterToast.show(
  'Payment received',
  description: '₹1,200 from Sam',
  style: ButterToastStyle.card,
);

• Pill hugs its text, like the platform toast. Great for "Copied" or "Saved".
• Card shows a title and description at full width. Several cards stack like a deck; tap (or hover on web) to spread them out.

While a stack is spread out, its timers pause so nothing disappears while you read. It closes again when you tap anywhere else, or on its own after 5 seconds without a touch, and then the toasts leave as usual.

👆 Swipe to dismiss #

Throw a toast in any direction to dismiss it: up, down, sideways or diagonally. A short drag springs back. In a spread-out stack every toast can be swiped on its own, including the ones in the middle. Pass dismissible: false to turn swiping off for a toast.

🧹 Repeated taps and tags #

Showing a toast identical to one already on screen restarts that toast instead of adding a copy, so a button tapped five times shows one toast.

For toasts whose text changes, give them a tag. A new toast with the same tag updates the existing one in place:

ButterToast.loading('Saving…', tag: 'save');
// later, or on the next tap:
ButterToast.success('Saved', tag: 'save'); // same toast, now a success

🖼️ Icons and the app icon #

By default, typed toasts show their own icon and plain show toasts show none. You can change that at three levels:

ButterToastAppIcon shows your app's launcher icon, the way Android shows it on native toasts. It's read from the platform at run time, so it always matches the icon on the home screen, with no asset to add or keep in sync:

// App-wide
ButterToastTheme(
  icon: ButterToastAppIcon(), // plain toasts show the app icon
  typeIcons: false,           // success, error, … show it too
)

// Or just on one toast
ButterToast.success('Order placed', icon: const ButterToastAppIcon());

Any widget works as an icon, such as Image.asset('assets/logo.png').

🎨 Theming: app-wide and per toast #

App-wide #

butter_toast reads a ThemeExtension, so light and dark themes just work:

MaterialApp(
  theme: ThemeData(
    extensions: const [
      ButterToastTheme(
        style: ButterToastStyle.card,
        position: ButterToastPosition.topCenter,
        duration: Duration(seconds: 3),
        bottomOffset: 80,        // above a NavigationBar
        maxHeightFraction: 0.4,  // height budget
        maxLines: 3,             // lines before "Show more"
        cardBorderRadius: 16,
        successColor: Color(0xFF16A34A),
      ),
    ],
  ),
  darkTheme: ThemeData.dark().copyWith(
    extensions: const [ButterToastTheme(style: ButterToastStyle.card)],
  ),
  builder: ButterToast.init(),
);

Not using ThemeData extensions? Pass it to init instead: ButterToast.init(theme: const ButterToastTheme(...)).

Per toast #

Want a different look on one screen or for one kind of message, like a dark checkout toast with your app icon? Pass theme: to that call. Set only the fields you want to change; everything else still comes from the app theme.

const checkoutToast = ButterToastTheme(
  style: ButterToastStyle.card,
  cardColor: Color(0xFF0F172A),
  cardForegroundColor: Colors.white,
  cardBorderColor: Color(0xFF1E293B),
  icon: ButterToastAppIcon(),
  typeIcons: false,
);

ButterToast.success('Payment done', theme: checkoutToast);
ButterToast.error('Card declined', theme: checkoutToast);

Keep the theme in a const and reuse it on every toast of that screen. Only the toasts you pass it to change; other toasts keep the app look.

A per-toast theme applies its colours, text style, shadows, radius, icons, maxLines, style, position and duration. Settings that shape the whole stack at a position (margin, maxWidth, gap, bottomOffset, visibleCount, maxToasts, maxHeightFraction) stay app-wide.

Which setting wins? #

From strongest to weakest:

1. A parameter on the call, such as position: or icon:
2. The call's theme:
3. ButterToast.init(theme: ...)
4. The ButterToastTheme in your ThemeData.extensions
5. The built-in defaults

🪟 Dialogs and bottom sheets #

Toasts live above the Navigator, so they always show on top of dialogs and bottom sheets, and aren't dimmed by their barrier.

Over a dialog	Over a bottom sheet

• Dialog: the toast appears at its usual position, above the dialog.
• Bottom sheet: a bottom toast floats over the sheet's lower edge. To keep the sheet clear, show it at the top:

ButterToast.success('Link copied', position: ButterToastPosition.topCenter);

📏 Long text, keyboard and safe area #

A toast never takes over the screen:

• All toasts at one position share a height budget: 40% of the safe height by default.
• Text that doesn't fit ends with Show more. Tapping it shows the full text, scrolling inside the toast if needed, and pauses the timer.
• When the keyboard opens, toasts move above it and the budget shrinks with the space left. If there's no room at all, bottom toasts move to the top.
• The notch, status bar, home indicator and landscape cutouts are always avoided. Use bottomOffset to float above your bottom navigation bar.

🧩 Fully custom toasts #

Draw anything; butter_toast still animates, stacks, times, positions and swipes it:

ButterToast.custom(
  builder: (context, toast) => MyBrandedToast(
    onClose: toast.dismiss,
  ),
  position: ButterToastPosition.topCenter,
);

🔁 Coming from fluttertoast? #

📱 Platforms #

Drawn in Flutter, so it looks the same everywhere. A small native part only reads the app icon for ButterToastAppIcon. Tested on a Galaxy A36 (Android 17) and on the web (Chromium); iOS hasn't been tested on a device yet.

🤝 Contributing #

Bugs, ideas and pull requests are welcome in the issue tracker. If butter_toast made your app a little smoother, a 👍 on pub.dev helps others find it.

📄 License #

MIT © Parth Bhensdadiya