auto_status_bar 1.0.0

Automatically adjust the status bar appearance (light/dark) based on the underlying screen content brightness.

auto_status_bar

A Flutter package that automatically switches the status bar between light and dark styles based on the actual screen content behind it.

Instead of manually managing SystemUiOverlayStyle on every page, auto_status_bar captures a low-resolution screenshot of the status bar region, computes the average luminance, and applies the correct overlay style — all transparently.

Features

• Automatic luminance-based status bar theme switching
• Built-in NavigatorObserver that refreshes on every route transition
• Waits for route transition animations to complete before analyzing
• Customizable light/dark SystemUiOverlayStyle themes
• Zero external dependencies (Flutter SDK only)
• Simple setup — just two lines in MaterialApp

Getting Started

Add the dependency to your pubspec.yaml:

dependencies:
  auto_status_bar: ^1.0.0

Then run:

flutter pub get

Usage

Basic setup

Wrap your app content with the provided capturer widget and register the navigator observer:

import 'package:auto_status_bar/auto_status_bar.dart';

MaterialApp(
  navigatorObservers: [AutoStatusBar.instance.observer],
  builder: (context, child) {
    return AutoStatusBarCapturer(child: child!);
  },
  home: const HomePage(),
);

That's it. The status bar style will now automatically adapt whenever you navigate between pages.

Manual setup (without AutoStatusBarCapturer)

If you prefer more control, attach the RepaintBoundary yourself:

MaterialApp(
  navigatorObservers: [AutoStatusBar.instance.observer],
  builder: (context, child) {
    return RepaintBoundary(
      key: AutoStatusBar.instance.key,
      child: child!,
    );
  },
  home: const HomePage(),
);

Custom theme

You can provide your own SystemUiOverlayStyle for the light and dark variants:

AutoStatusBar.instance.setTheme(
  StatusBarTheme(
    darkTheme: const SystemUiOverlayStyle(
      statusBarColor: Colors.transparent,
      statusBarIconBrightness: Brightness.dark,
    ),
    lightTheme: const SystemUiOverlayStyle(
      statusBarColor: Colors.transparent,
      statusBarIconBrightness: Brightness.light,
    ),
  ),
);

Manual refresh

If the screen content changes without a route transition (e.g., a theme toggle or scroll event), you can trigger a manual refresh:

await AutoStatusBar.instance.refresh();

How It Works

1. A RepaintBoundary captures the rendered screen at 20% resolution for performance.
2. The pixels in the status bar region are read as raw RGBA bytes.
3. The average luminance is computed using the ITU-R BT.601 formula: L = 0.299 * R + 0.587 * G + 0.114 * B
4. If the average luminance exceeds 128 (bright), dark icons are applied; otherwise light icons are applied.
5. The StatusBarObserver hooks into Flutter's navigation lifecycle so this process runs automatically on every page transition.

API Reference

AutoStatusBar

Member	Description
AutoStatusBar.instance	Singleton instance
.observer	NavigatorObserver for automatic refresh
.key	GlobalKey to attach to a RepaintBoundary
.theme	Current StatusBarTheme
.setTheme(StatusBarTheme)	Replace the current theme
.refresh()	Manually trigger a luminance analysis and style update
.setDarkTheme()	Force-apply the dark overlay style
.setLightTheme()	Force-apply the light overlay style

StatusBarTheme

Parameter	Description
darkTheme	SystemUiOverlayStyle for bright backgrounds (dark icons)
lightTheme	SystemUiOverlayStyle for dark backgrounds (light icons)

AutoStatusBarCapturer

A convenience widget that wraps its child in a keyed RepaintBoundary. Accepts an optional theme parameter.

StatusBarObserver

A NavigatorObserver that calls refresh() after route transitions complete.

License

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