hud_overlay

pub version license: MIT platform

hud_overlay — Flutter loading overlay. Context-free. Accessible.

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

Libraries

hud_overlay