Async State


iOS Android Mac Linux Windows


1 - Wrap your MaterialApp Or CurpertinoApp with the AsyncStateBuilder.
2 - Get the "navigatorObserver" from the builder function and add it to your component's "navigatorObservers".
3 - If you want, you can add a widget to "CustomLoader", exceptionHandlers or disable the log.

Code example:

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  Widget build(BuildContext context) {
    /// Here you need to wrap your MaterialApp with the AsyncStateBuilder
    return AsyncStateBuilder(
      /// Here you can customize your default loading that will show every transaction
      /// Leave it and it will show a simple CircularProgress.adaptive indicator
      customLoader: const GlobalLoading(),

      /// Here you can enable or disable the log
      enableLog: true,

      ///You can customize your exceptions handlers for route
      exceptionHandlers: {
        '_': GlobalExceptionHandler(),
        '/Home/Detail': DetailExceptionHandler(),
      builder: (navigatorObserver) => MaterialApp(
        themeMode: ThemeMode.dark,
        theme: ThemeData.dark(),

        /// Here you need to pass the navigatorObserver to the MaterialApp
        navigatorObservers: [navigatorObserver],
        initialRoute: '/Home',
        routes: {
          '/Home': (context) => const HomePage(),
          '/Home/Detail': (context) => const DetailPage(),
          '/Home/Detail/SecondDetail': (context) => const SecondDetailPage(),


All methods allow you to customize the “loader”, when you change the "enum LoaderType", you need to ensure that the "customLoader" is already a widget of the same type.

Method - (Extension) asyncState

Use the “asyncState” extension in asynchronous calls, you won't have to worry about opening or closing the “loader”.

 Future<void> loginSuccess() async {
    final result = await _functionSuccess().asyncLoader();
    debugPrint('Login Success result: $result');

Future<void> loadMorePersonalized() async {
    await _functionFailure().asyncLoader(
      customLoader: HomeCustomLoaderSnackbar(),
      loaderType: LoaderType.snackBar,

Method - (Class OR Context Extension) AsyncLoaderHandler

The "AsyncLoaderHandler" method, allows you to have control over the open loader. Don't worry about “exceptions”, "asyncState" will close the loader if an “exception” is raised before you call “close”.

 Future<void> loginSuccessHandler() async {
    final handler = AsyncLoaderHandler.start();
    final result = await _functionSuccess().asyncLoader();
    debugPrint('Login Success result: $result');

///OR On View
  onPressed: () async {
    await errorCall();
  child: const Text('Loader Error by context'),

Method - (Interface Class) AsyncStateExceptionHandler

You can create a class that extends "AsyncStateExceptionHandler", with it, you can handle “exceptions” automatically and per route.

It is necessary to check the "exception.runtimeType", or it will execute the action in any “exception”.

class DetailExceptionHandler implements AsyncStateExceptionHandler {
  void onException(
    Object exception,
    StackTrace stackTrace,
    BuildContext context,
  ) {
    switch (exception.runtimeType) {
      case DetailException:
            content: Text(
      case _:

On Main

In “main”, you can define a specific “AsyncStateExceptionHandler” for each route. The “_” is global, it will be used if the current route does not have a unique “AsyncStateExceptionHandler”.

 ///You can customize your exceptions handlers for route
exceptionHandlers: {
  '_': GlobalExceptionHandler(),
  '/Home/Detail': DetailExceptionHandler(),

Bugs or Requests

If you encounter any problems feel free to open an issue. If you feel the library is missing a feature, please raise a ticket on GitHub and I'll look into it. Pull request are also welcome.


Leonardo Serrano

Marcus Brasizza

Felipe Sales

If you like what I do, maybe consider buying me a coffee/tea 🥺👉👈

Buy Me A Coffee