Flutter EasyLoading

🌐 English | 简体中文

A lightweight, customizable loading, progress, result, and toast overlay for Flutter. Display calls do not require a BuildContext.

• Loading, determinate progress, result states, and toast messages
• Global calls without passing a BuildContext
• Built-in indicators, custom widgets, and custom transitions
• Global defaults with immutable per-call overrides
• Material and Cupertino application support

🎬 Preview

Open the interactive Flutter EasyLoading preview

🧰 Requirements

• Dart 3.6.0 or later, below Dart 4.0.0
• Flutter 3.27.0 or later

Read the 4.0 migration guide before upgrading from 3.x.

📦 Installation

flutter pub add flutter_easyloading

Or add the dependency manually:

dependencies:
  flutter_easyloading: ^4.0.2

import 'package:flutter_easyloading/flutter_easyloading.dart';

🚀 Quick Start

Install one EasyLoading Host at the root MaterialApp or CupertinoApp:

MaterialApp(
  builder: EasyLoading.init(),
  home: const HomePage(),
);

Display and dismiss content from anywhere after the Host is mounted:

await EasyLoading.show(status: 'Loading...');
await EasyLoading.showProgress(0.5, status: 'Downloading...');

await EasyLoading.showSuccess('Completed');
await EasyLoading.showError('Request failed');
await EasyLoading.showInfo('Update available');
await EasyLoading.showToast('Saved');

await EasyLoading.dismiss();

All display and dismissal methods return Future<void> and can be awaited.

If the application already has a root builder, compose it through init:

MaterialApp(
  builder: EasyLoading.init(
    builder: (context, child) => ExistingRoot(child: child),
  ),
  home: const HomePage(),
);

📖 API Reference

Initialization and state

Display and dismissal

Callbacks

void onStatus(EasyLoadingStatus status) {
  // EasyLoadingStatus.show or EasyLoadingStatus.dismiss
}

void onDismiss(EasyLoadingDismissReason reason) {
  // programmatic, tap, timeout, or hostDetached
}

EasyLoading.addStatusCallback(onStatus);
EasyLoading.addDismissCallback(onDismiss);

// Remove callbacks when their owner is disposed.
EasyLoading.removeCallback(onStatus);
EasyLoading.removeDismissCallback(onDismiss);

⚙️ Configuration

Set global defaults once during application startup:

EasyLoading.instance
  ..loadingStyle = EasyLoadingStyle.dark
  ..indicatorType = EasyLoadingIndicatorType.fadingCircle
  ..maskType = EasyLoadingMaskType.none
  ..toastPosition = EasyLoadingToastPosition.bottom
  ..displayDuration = const Duration(seconds: 2)
  ..animationDuration = const Duration(milliseconds: 200);

General

Layout and text

Colors and effects

Custom widgets and animation

Custom modes require their corresponding values:

• EasyLoadingStyle.custom: backgroundColor, indicatorColor, and textColor; progress also requires progressColor.
• EasyLoadingMaskType.custom: maskColor.
• EasyLoadingAnimationStyle.custom: customAnimation.

🎛️ Per-call Options

EasyLoadingOptions is an immutable snapshot for one display call. Every field is optional and inherits the corresponding global value when omitted.

maskType, dismissOnTap, and duration remain direct method parameters. toastPosition is a direct parameter of showToast.

await EasyLoading.show(
  status: 'Uploading',
  maskType: EasyLoadingMaskType.black,
  duration: const Duration(seconds: 10),
  options: const EasyLoadingOptions(
    loadingStyle: EasyLoadingStyle.auto,
    alignment: AlignmentDirectional.topEnd,
    constraints: BoxConstraints(maxWidth: 320),
    indicatorType: EasyLoadingIndicatorType.ring,
  ),
);

🧩 Public Types

All EasyLoadingIndicatorType values

fadingCircle, circle, threeBounce, chasingDots, wave, wanderingCubes, rotatingPlain, doubleBounce, fadingFour, fadingCube, pulse, cubeGrid, rotatingCircle, foldingCube, pumpingHeart, dualRing, hourGlass, pouringHourGlass, fadingGrid, ring, ripple, spinningCircle, squareCircle, dancingSquare, pianoWave, pouringHourGlassRefined, pulsingGrid, spinningLines, threeInOut, and waveSpinner.

🎨 Custom Content

await EasyLoading.showCustom(
  const Material(
    child: Padding(
      padding: EdgeInsets.all(16),
      child: Text('Custom content'),
    ),
  ),
  maskType: EasyLoadingMaskType.black,
  options: const EasyLoadingOptions(
    alignment: AlignmentDirectional.bottomCenter,
    constraints: BoxConstraints(maxWidth: 320),
  ),
);

See the example application's custom animation for an EasyLoadingAnimation implementation.

🔄 Migrating From 3.x

Common init, show..., dismiss, status callback, and EasyLoading.instance call forms remain valid. Review the SDK baseline and removed undocumented internals in the 4.0 migration guide.

🗂️ Project

• Example application
• Changelog
• Contributing
• Security policy
• Issue tracker

⚖️ License

Flutter EasyLoading is available under the MIT License.

🙏 Credits

Built-in loading indicators are provided by flutter_spinkit.