Anatomy of the System Bars in Flutter: Status Bar and Navigation Bar with SystemUiOverlayStyle

I have had App Store submissions rejected because of the status bar. The problem was contrast: the color of the system icons did not match the screen background, and the information at the top was hard to read. On Android, the same slip usually shows up at the bottom, with a white back icon on a white navigation bar, and the user cannot find a way out of the screen.

This kind of mistake does not depend on the framework, but in Flutter it shows up on both platforms at once: the same code draws the screen on Android and iOS, and each system reads a different property to decide the icon color. That is why I decided to write about the anatomy of these bars, how they behave and how to configure them in Flutter.

What belongs to the system and what belongs to the app

On Android, the screen has two strips that do not belong to the app. At the top is the status bar, with time, network and battery, sharing space with the camera cutout. At the bottom is the navigation bar, which can be the 3-button one (back, home and recents) or just the gesture bar. iOS has no navigation bar: the bottom has the home indicator, and the top shares the status bar with the notch or the Dynamic Island.

In neither of them does the app draw the icons on these bars. What it controls is two things: what shows behind them and whether the system icons will be light or dark. The first answer comes from the app layout. The second is a setting many people never touch, and it decides whether the time and the back button will be readable.

The mistake that usually happens

This mistake reaches the store because it depends on context. Developers usually test with one theme and one navigation mode, most often gestures, where the bottom bar barely shows. The user runs the dark theme, or 3-button navigation, or lands on a screen without an AppBar, like the splash, the onboarding or a video player. Those screens inherit the style of the previous screen, which was designed for a different background.

The belief behind the problem is "the bar belongs to the system, so the system takes care of it". Part of it is true: the operating system is what draws the time and the battery. But the color of those icons is the app's decision, and the system does not check whether it matches what sits behind it.

Edge-to-edge changed the rule on Android

For a long time, the fix was to paint the status bar with the app color. Starting with Android 15, every app with targetSdk 35 draws edge to edge by default: content goes behind the status bar and the navigation bar. setStatusBarColor is now ignored, gesture navigation is transparent and 3-button navigation gets a translucent background at 80% opacity. Android 15 still let you opt out of this behavior, but for apps with targetSdk 36, on Android 16, that option is gone.

Flutter users are already in this scenario too. Since version 3.27, the default Flutter project uses targetSdk 35, so any updated app runs edge-to-edge on Android 15.

In practice, two responsibilities are left. The first is choosing the icon color according to the background that will sit behind it. The second is applying the insets, the measures of how much each bar takes up, so the background runs behind them but interactive content does not end up under the clock or the gesture bar.

How each framework names light and dark

Before writing any code, answer one question: is the background behind the bar light or dark? A light background calls for dark icons, and a dark background calls for light icons.

The confusion is that each framework names this differently. In Flutter, the name describes the icon, so dark icons are dark. In Compose and SwiftUI, the name describes the background, so the same dark icons are light.

One detail about Flutter's presets: SystemUiOverlayStyle.dark and SystemUiOverlayStyle.light only change the status bar. In both, the navigation bar comes out black with light buttons, so it has to be configured separately, as in the example in the next section.

In Flutter: SystemUiOverlayStyle

The starting point is defining a default style in main, before runApp:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

const defaultStyle = SystemUiOverlayStyle(
  // Android: transparent bars and dark icons
  statusBarColor: Colors.transparent,
  statusBarIconBrightness: Brightness.dark,
  systemNavigationBarColor: Colors.transparent,
  systemNavigationBarIconBrightness: Brightness.dark,
  systemNavigationBarContrastEnforced: true,
  // iOS: light background behind the status bar, so dark text
  statusBarBrightness: Brightness.light,
);

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);
  SystemChrome.setSystemUIOverlayStyle(defaultStyle);
  runApp(const MyApp());
}

Notice that iOS uses a different property. statusBarIconBrightness only applies on Android and describes the icon, so it is Brightness.dark. statusBarBrightness only applies on iOS and describes the background, so it is Brightness.light, even though the result is the same dark text.

systemNavigationBarContrastEnforced lets Android keep the translucent background on 3-button navigation, which is the protection against the invisible back button. The transparent statusBarColor changes nothing in apps with targetSdk 35 or higher, but keeps the same look on older apps and versions.

This global style loses to the AppBar, which publishes its own style on top of what was set in main. If the screen has an AppBar, the configuration has to go into the theme, in AppBarTheme(systemOverlayStyle: defaultStyle). Without it, Flutter computes a style from the AppBar background color.

For screens that break from the default, the tool is AnnotatedRegion. It declares the style of one part of the widget tree, and Flutter applies the style of whichever region sits under each bar:

class PlayerScreen extends StatelessWidget {
  const PlayerScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return AnnotatedRegion<SystemUiOverlayStyle>(
      value: SystemUiOverlayStyle.light.copyWith(
        statusBarColor: Colors.transparent,
        systemNavigationBarColor: Colors.transparent,
      ),
      child: const Scaffold(
        backgroundColor: Colors.black,
        body: SafeArea(
          child: Center(
            child: Icon(Icons.play_circle, color: Colors.white, size: 96),
          ),
        ),
      ),
    );
  }
}

When the user goes back to the previous screen, the player region leaves the tree and the previous style comes back on its own, with nothing to undo. SafeArea takes care of the insets: the black background fills the whole screen and the content stays inside the free area. In lists, ListView already does this by itself, because without an explicit padding it uses the MediaQuery padding.

Before sending it to the store

Most of these mistakes only show up in a specific combination of theme, navigation and screen. Before each submission, it is worth going through four scenarios:

Light and dark theme. Switch the system theme with the app open and go through every screen.

3-button navigation. Turn it on in the Android settings. That is where the back button disappears when the contrast is wrong.

Screens without an AppBar. Splash, onboarding, player, camera and any screen with an image behind the status bar.

iPhone with a notch or Dynamic Island, in light and dark mode. On iOS, the background behind the status bar is always the app's, so test the dark screens with the device in light mode and the light screens in dark mode.

The rule that holds for any framework

Every decision about the system bars starts with the color of the background behind them. With that answer, the name of each API becomes a translation detail, and the rest is applying the insets so the content does not end up under the clock or the gestures.

None of these APIs checks your configuration. Android's translucent background protects 3-button navigation and the default iOS style tries to keep contrast, but when the app declares the wrong color, the white icon on a white background reaches the store review all the same.

After the bars, the next step is the other insets edge-to-edge left exposed: the keyboard, the camera cutout when the app rotates to landscape and the fold on foldable devices. In all of them the system takes up part of the screen, and the app needs to know which part.