auto_status_bar 1.1.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
• Configurable luminance threshold (default 128, range 0–255)
• 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.1.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,
    ),
  ),
);

Custom luminance threshold

The default threshold of 128 works well for most apps. If you find the status bar switching too eagerly or too late, tune it:

// Bias towards dark icons — switch only on very bright backgrounds.
AutoStatusBar.instance.setThreshold(160);

You can also set it once via AutoStatusBarCapturer:

AutoStatusBarCapturer(
  threshold: 160,
  child: child!,
)

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 the threshold (default 128, configurable), 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
.threshold	Current luminance threshold (0–255, default 128)
.setThreshold(double)	Update the luminance threshold at runtime
.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 optional theme and threshold parameters.

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.