elegant_loading_overlay #

Beautiful, customizable loading overlay for Flutter with a one-line API. Features 11 built-in loaders, smooth animations, progress indicators, blur backgrounds, theme support, and full platform compatibility.

✨ Features #

• 🚀 One-line API — LoadingOverlay.show() / LoadingOverlay.hide()
• 🎨 11 Built-in Loaders — Circular, Dots, Pulse, Ripple, Bars, Cube, Ring, Gradient Spinner, Minimal Spinner, Material Spinner, Cupertino Spinner
• 🎬 Smooth Animations — Fade, Scale, Slide, Zoom, Rotation
• 🌫️ Blur Background — Configurable blur sigma
• 📊 Progress Indicators — Determinate and indeterminate
• 💬 Messages & Subtitles — Customizable text content
• 🎯 Custom Builder — Full control with custom widgets
• 🎭 Theme Support — LoadingOverlayTheme for consistent styling
• 🔒 Stacking Protection — Only one overlay at a time
• ♿ Accessibility — Full semantics support
• 🌍 Cross-Platform — Android, iOS, Web, macOS, Windows, Linux
• 🌙 Dark Mode — Fully supported
• 📱 Responsive — Mobile, Tablet, Desktop
• ⚡ Performant — RepaintBoundary, ValueNotifier, const widgets
• 🧪 Well Tested — Comprehensive widget and unit tests
• 📦 Zero Dependencies — Flutter SDK only

📦 Installation #

Add to your pubspec.yaml:

dependencies:
  elegant_loading_overlay: ^0.0.1

Then run:

flutter pub get

🚀 Quick Start #

import 'package:elegant_loading_overlay/elegant_loading_overlay.dart';

// Show
LoadingOverlay.show(context: context);

// Hide
await LoadingOverlay.hide();

📖 Usage #

Basic Loading #

LoadingOverlay.show(context: context);

await doSomeWork();

await LoadingOverlay.hide();

With Message #

LoadingOverlay.show(
  context: context,
  message: 'Loading...',
);

With Message & Subtitle #

LoadingOverlay.show(
  context: context,
  message: 'Uploading file',
  subtitle: 'This may take a moment',
);

With Progress #

LoadingOverlay.show(
  context: context,
  message: 'Downloading...',
  progress: 0.45,
);

Dismissible #

LoadingOverlay.show(
  context: context,
  dismissible: true,
  onDismiss: () => print('Dismissed!'),
);

Check Status & Toggle #

if (LoadingOverlay.isShowing) {
  await LoadingOverlay.hide();
}

// Or toggle
await LoadingOverlay.toggle(context: context);

Custom Animation #

LoadingOverlay.show(
  context: context,
  animation: LoadingAnimationType.scale,
  animationDuration: const Duration(milliseconds: 400),
  animationCurve: Curves.easeOutBack,
);

Different Loaders #

// Dots loader
LoadingOverlay.show(
  context: context,
  loaderType: LoaderType.dots,
);

// Pulse loader
LoadingOverlay.show(
  context: context,
  loaderType: LoaderType.pulse,
);

// Ripple loader
LoadingOverlay.show(
  context: context,
  loaderType: LoaderType.ripple,
);

// ... and 8 more!

Custom Loader (Builder) #

LoadingOverlay.show(
  context: context,
  builder: (_) => const Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      Icon(Icons.cloud_upload, size: 48, color: Colors.blue),
      SizedBox(height: 16),
      Text('Uploading...'),
    ],
  ),
);

Blur & Styling #

LoadingOverlay.show(
  context: context,
  enableBlur: true,
  blurSigma: 5.0,
  barrierColor: Colors.black54,
  backgroundColor: Colors.white,
  loaderColor: Colors.teal,
  borderRadius: BorderRadius.circular(20),
  elevation: 12,
);

Context Extensions #

// Show
context.showLoadingOverlay(message: 'Loading...');

// Hide
context.hideLoadingOverlay();

🎨 Theming #

Wrap your app with LoadingOverlayTheme for consistent styling:

LoadingOverlayTheme(
  data: LoadingOverlayThemeData(
    loaderColor: Colors.tealAccent,
    backgroundColor: Colors.grey.shade900,
    messageTextStyle: const TextStyle(
      color: Colors.white,
      fontSize: 16,
    ),
    blurSigma: 5.0,
    animationDuration: const Duration(milliseconds: 400),
    animationType: LoadingAnimationType.scale,
    loaderType: LoaderType.gradientSpinner,
  ),
  child: MaterialApp(
    home: MyHomePage(),
  ),
)

🔧 Scoped Overlays #

Use LoadingOverlayScope for independent overlay control in different parts of your app:

LoadingOverlayScope(
  theme: const LoadingOverlayThemeData(
    loaderColor: Colors.purple,
  ),
  child: MyPage(),
)

// In MyPage:
final scope = LoadingOverlayScope.of(context);
scope.show();
await scope.hide();

🎬 Available Animations #

🎡 Built-in Loaders #

📐 API Reference #

LoadingOverlay (Static API) #

LoadingOverlayConfig #

All configuration options for show():

🌍 Platform Support #

⚡ Performance Notes #

• Uses RepaintBoundary to isolate overlay repaints
• ValueNotifier-based controller avoids stream overhead
• const constructors used throughout
• CustomPainter-based loaders for efficient rendering
• Stacking protection prevents duplicate overlay creation

❓ FAQ #

Q: Can I show multiple overlays at once? A: The global LoadingOverlay API enforces single-overlay mode. Use LoadingOverlayScope for independent overlays in different subtrees.

Q: What happens if I call hide() without calling show()? A: Nothing. The method safely returns without error.

Q: What happens if I call show() twice? A: The existing overlay is updated with the new configuration — no duplicate overlay is created.

Q: Does it work with Navigator.push? A: Yes. The overlay is inserted into the root Overlay and appears above all routes.

Q: Does it support keyboard avoidance? A: Yes. The overlay content is properly positioned to avoid keyboard overlap.

🗺️ Roadmap #

• ❌ Shimmer effect loader
• ❌ Lottie animation support
• ❌ Progress stream support
• ❌ Global configuration
• ❌ Timeout with auto-dismiss
• ❌ Success/Error state transitions
• ❌ Haptic feedback option
• ❌ Sound effect option

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide and Code of Conduct first.

📄 License #

This project is licensed under the MIT License — see the LICENSE file for details.