fluttertoast: two different toasts behind one package name

Two APIs, and they are not variants of each other

fluttertoast is a toast library for Flutter, and the first thing the project tells you is that it supports two kinds of toast messages: one which requires a BuildContext and one with no BuildContext.

That distinction is easy to skim past and it is the single most important thing to know about this package, because the two APIs have almost nothing in common beyond the name.

The context-free one is a static call, Fluttertoast.showToast, that delegates to whatever the platform's own toast mechanism is. Its supported platforms are Android, iOS and Web, and on the web it uses Toastify-JS. The stated limitation is blunt: this one has limited features and no control over UI. You get a message, a length, a gravity position, and on the native platforms the platform renders the rest.

The BuildContext one is a different mechanism entirely. Its supported platforms are ALL, and it gives you four things: full control of the toast, toasts will be queued, the ability to remove a toast, and the ability to clear the queue. It works by rendering a widget you supply, in an overlay that the library manages.

So a team asking whether fluttertoast supports their use case should first answer a different question: do they want the platform toast, with its native look and its limitations, or a custom widget, which is really a different package sharing a name and an import path? The README presents them as two features of one library, and they are better understood as two implementations.

The context-free call and its property table

The context-free API is one call with a set of named parameters, and the property table in the README is the reference.

Fluttertoast.showToast(
        msg: "This is Center Short Toast",
        toastLength: Toast.LENGTH_SHORT,
        gravity: ToastGravity.CENTER,
        timeInSecForIosWeb: 1,
        backgroundColor: Colors.red,
        textColor: Colors.white,
        fontSize: 16.0
    );

The msg property is the only required one, and it must not be null. toastLength takes Toast.LENGTH_SHORT or Toast.LENGTH_LONG and defaults to LENGTH_SHORT. gravity takes ToastGravity.TOP, CENTER or BOTTOM, defaults to BOTTOM, and the web implementation only supports top and bottom. timeInSecForIosWeb is an int in seconds for iOS and web, defaulting to 1.

Then there is the styling group: backgroundColor, textColor and fontSize, all nullable with no default, and fontAsset, which takes the path to a font file in the Flutter app assets folder, for example a path ending in some-font.ttf.

The web-only properties are worth reading separately because they show that the web path is a distinct implementation. webShowClose is a bool defaulting to false, webBgColor is a hex colour string defaulting to a linear-gradient(to right, #00b09b, #96c93d), and webPosition takes left, center or right and defaults to right.

Cancelling everything is one call:

Fluttertoast.cancel()

Note the inconsistency in the API surface. The parameter is textColor in the Dart code and the table lists it as textcolor in one place, and the FToast API uses child and toastDuration where the static API uses msg and toastLength. Small things, but they are the kind of thing you hit when you paste a snippet from the wrong section.

Android 11 and the end of custom native toasts

There is a warning in the README with a screenshot next to it, and it is the most practically important line in the document for Android developers.

Custom Toast will not work on Android 11 and above. It will only use msg and toastLength, and the remaining properties are ignored.

That is a platform change rather than a library bug. Android 11 deprecated the custom toast view that the library was using to render its own layout, and the system now takes over the rendering, so the library can only influence the message and how long it stays.

The consequence is that the styling parameters you would most want to set, backgroundColor, textColor, fontSize and fontAsset, are silently ignored on any modern Android device. On a device running Android 10 or earlier they still work.

There is a documented workaround for the styling, and it is an Android resource rather than a Dart one. You create a file named toast_custom.xml in your project app/res/layout folder and do the custom styling there, with a FrameLayout containing a TextView that sets the background drawable, the padding and the text colour. The library then picks up that layout for its native toast.

So the platform split is real. On Android, the native toast is the platform toast, and customisation happens in XML. On iOS and web, the parameters apply directly. The FToast path is the one that behaves identically everywhere, because it never touches the native toast at all.

The FToast path renders your own widget

The BuildContext-based API works in the opposite way, and it is a genuinely different tool.

The setup step is to update your MaterialApp with a builder, using FToastBuilder, and to pass a navigatorKey so the library can reach the context globally:

MaterialApp(
    builder: FToastBuilder(),
    home: MyApp(),
    navigatorKey: navigatorKey,
),

Then you create an FToast instance in initState and initialise it with the context:

FToast fToast;

@override
void initState() {
    super.initState();
    fToast = FToast();
    // if you want to use context from globally instead of content we need to pass navigatorKey.currentContext!
    fToast.init(context);
}

The comment in that snippet is a real gotcha. If you want to use the context globally rather than a local one, you have to pass navigatorKey.currentContext instead, which is exactly why the navigatorKey is in the MaterialApp setup above.

The show call takes your widget directly:

fToast.showToast(
    child: toast,
    gravity: ToastGravity.BOTTOM,
    toastDuration: Duration(seconds: 2),
);

And the child is an ordinary Flutter widget, so a toast can be a Container with a border radius, a colour and a Row of an Icon and a Text, exactly as the example builds. Because it is a widget, you can also position it yourself with the positionedToastBuilder callback, which takes a context and a child and returns a Positioned wrapper, so you can pin the toast to a corner rather than using gravity at all.

The property table for this path lists child as required, toastDuration, gravity, positionedToastBuilder, fadeDuration with a default of 350 milliseconds, ignorePointer defaulting to false, and isDismissible.

What the repository contains, and what the package is

The repository layout is the standard Flutter package shape with one extra file worth noting.

There is lib/ for the Dart source, android/ and ios/ for the native side, assets/, an example/ directory with its own full project including android, ios, linux, macos, web and windows subdirectories, and a screenshot/ directory. The example project covering six desktop and mobile platforms is itself a signal, because it means the package is expected to build and run everywhere rather than only on a phone.

There is a pubspec.yaml and pubspec.lock, a .metadata file, a .pubignore, and a CHANGELOG.md and CONTRIBUTING.md. The package is published on pub.dev as fluttertoast, and the README links that page as the title.

The unusual file is ErrorSolvedTesting.dart at the repository root, next to fluttertoast.iml and the .DS_Store that every macOS developer accidentally commits. A file named after a specific bug class at the top level of a package repository usually means somebody hit a problem, wrote a reproduction, and left it where it would be noticed. It is not something the published package would contain, since the pubspec controls what ships, but it is a reasonable artefact for a maintainer to keep.

The build checks badge points at a GitHub Actions workflow called Build Checks, so the package is built across platforms in CI, and the repository is not archived with the last push on 2026-10-02. There are no GitHub releases, which is normal for a pub.dev package, where the pubspec version and the CHANGELOG are the release history. The dependency line in the README is fluttertoast at ^10.0.2, so the current major is 10.

Editorial conclusion

fluttertoast is a good pick for a Flutter app that wants a native-looking toast with no widget tree involvement, because the context-free call works the same on Android, iOS and the web and needs no BuildContext at all; it is the wrong pick if you need a fully custom toast on Android, because custom native toasts stopped working on Android 11 and above and only the message and length are honoured, so before you adopt it you should decide which of the two APIs you actually want, since the FToast builder is a different library with a different feature set sitting behind the same package name.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ponnamkarthik/FlutterToast on GitHub
4. README