hud_overlay 0.1.1

A state-management-agnostic, accessibility-first, context-optional Flutter loading overlay. Works in widget trees, BLoC, Riverpod, and service layers with zero boilerplate.

hud_overlay

A simple loading spinner for your Flutter app that you can show from anywhere.

Whenever your app is busy — saving, loading, uploading — you usually want to show a spinner and gently block the screen until it's done. hud_overlay makes that a one-liner, and you don't need to pass context around to do it.

Why you'll like it

• Show it from anywhere. Call one line from a button, a service, BLoC, or Riverpod — no BuildContext required.
• Tell the user what's happening. Add a message, show real progress, or flip to a ✓ success or ✗ error when you're done.
• Looks good out of the box. Sensible light and dark styles, with the freedom to customize everything.
• Works for everyone. Built-in screen-reader support so visually impaired users aren't left guessing.
• No extra baggage. Pure Dart, no other dependencies, runs on every platform Flutter supports.

What it looks like

Each example below is its own screen in the example app.

Basic spinner HudOverlay(isLoading: true)	Message label HudOverlay(message: '…')	Determinate progress HudOverlay(progress: 0.0–1.0)
Detail line HudOverlay(detail: '…')	Cancel button HudOverlay(onCancel: …)	Backdrop blur HudTheme(blur: …)
Info toast HudService.showInfo(…)	Error state HudService.showError(…)	Custom state widgets HudTheme(successWidget: …)

Get started

1. Add it

dependencies:
  hud_overlay: ^0.1.0

Then run flutter pub get.

2. Pick how you want to use it

There are two ways. Use whichever feels easier — you can mix both.

Option A — wrap a widget

Great when the loading belongs to one screen or form. Just wrap it and flip a boolean:

HudOverlay(
  isLoading: _isSaving,      // true = show the spinner
  message: 'Saving…',
  child: MyForm(),
)

Option B — call it from anywhere

Great for app-wide loading from buttons, services, BLoC, or Riverpod.

First, turn it on once when your app starts:

MaterialApp(
  builder: (context, child) => HudScope(child: child!),
  home: const HomePage(),
)

Now show and hide it from anywhere — no context needed:

HudService.show(message: 'Saving…');
await saveToServer();
HudService.showSuccess(message: 'Saved!');   // shows a ✓ and disappears

Handy things you can do

Run a task and show the result automatically. Spinner while it runs, ✓ if it works, ✗ if it fails:

await HudService.wrap(
  api.save(),
  message: 'Saving…',
  successMessage: 'Saved!',
  errorMessage: 'Something went wrong',
);

Show real progress (like a download) from 0% to 100%:

HudService.show(progress: 0.42, message: '42%');

Quick messages:

HudService.showSuccess(message: 'Done!');
HudService.showError(message: 'No internet connection');
HudService.showInfo(message: 'Copied to clipboard');

Hide it whenever you need to:

HudService.dismiss();

Make it match your app

Want a different look? Pass a HudTheme. Start from a ready-made light or dark style and tweak only what you want:

HudOverlay(
  isLoading: _isLoading,
  theme: HudTheme.dark().copyWith(blur: 8), // dark style with a blurred background
  child: child,
)

With HudTheme you can change the background dimming, blur, spinner, card shape, position (top/center/bottom), text styles, and more. You can even add a Cancel button, haptic feedback, or let people keep tapping the screen while it loads.

The pieces

Name	What it's for
HudOverlay	A widget that shows a loading spinner over its child.
HudService	Show/hide loading from anywhere (show, showSuccess, showError, showInfo, dismiss, wrap, …).
HudScope	Set up once so HudService works app-wide.
HudTheme	Controls how everything looks and behaves.

See it in action

The example app has a dedicated, tap-to-try screen for every feature — the easiest way to see what's possible.

License

MIT — free to use in personal and commercial projects.