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

A RepaintBoundary captures the rendered screen at 20% resolution for performance.
The pixels in the status bar region are read as raw RGBA bytes.
The average luminance is computed using the ITU-R BT.601 formula: L = 0.299 * R + 0.587 * G + 0.114 * B
If the average luminance exceeds the threshold (default 128, configurable), dark icons are applied; otherwise light icons are applied.
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.