setSystemUIOverlayStyle static method

void setSystemUIOverlayStyle(
  1. SystemUiOverlayStyle style
)

Specifies the style to use for the system overlays (e.g. the status bar on Android or iOS, the system navigation bar on Android) that are visible (if any).

This method will schedule the embedder update to be run in a microtask. Any subsequent calls to this method during the current event loop will overwrite the pending value, such that only the last specified value takes effect.

Call this API in code whose lifecycle matches that of the desired system UI styles. For instance, to change the system UI style on a new page, consider calling when pushing/popping a new PageRoute.

The AppBar widget automatically sets the system overlay style based on its AppBar.systemOverlayStyle, so configure that instead of calling this method directly. Likewise, do the same for CupertinoNavigationBar via CupertinoNavigationBar.backgroundColor.

If a particular style is not supported on the platform, selecting it will have no effect.

The following example uses an AppBar to set the system status bar color and the system navigation bar color.
link

To create a local project with this code sample, run:
flutter create --sample=services.SystemChrome.setSystemUIOverlayStyle.1 mysample 

import 'dart:math' as math;

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

/// Flutter code sample for [AppBar.systemOverlayStyle].

void main() => runApp(const SystemOverlayStyleApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        useMaterial3: true,
        brightness: Brightness.light,
      ),
      home: const SystemOverlayStyleExample(),
    );
  }
}

class SystemOverlayStyleExample extends StatefulWidget {
  const SystemOverlayStyleExample({super.key});

  @override
  State<SystemOverlayStyleExample> createState() =>
      _SystemOverlayStyleExampleState();
}

class _SystemOverlayStyleExampleState extends State<SystemOverlayStyleExample> {
  final math.Random _random = math.Random();
  SystemUiOverlayStyle _currentStyle = SystemUiOverlayStyle.light;

  void _changeColor() {
    final Color color = Color.fromRGBO(
      _random.nextInt(255),
      _random.nextInt(255),
      _random.nextInt(255),
      1.0,
    );
    setState(() {
      _currentStyle = SystemUiOverlayStyle.dark.copyWith(
        statusBarColor: color,
        systemNavigationBarColor: color,
      );
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('SystemUiOverlayStyle Sample'),
        systemOverlayStyle: _currentStyle,
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: _changeColor,
          child: const Text('Change Color'),
        ),
      ),
    );
  }
}

For more complex control of the system overlay styles, consider using an AnnotatedRegion widget instead of calling setSystemUIOverlayStyle directly. This widget places a value directly into the layer tree where it can be hit-tested by the framework. On every frame, the framework will hit-test and select the annotated region it finds under the status and navigation bar and synthesize them into a single style. This can be used to configure the system styles when an app bar is not used. When an app bar is used, apps should not enclose the app bar in an annotated region because one is automatically created. If an app bar is used and the app bar is enclosed in an annotated region, the app bar overlay style supersedes the status bar properties defined in the enclosing annotated region overlay style and the enclosing annotated region overlay style supersedes the app bar overlay style navigation bar properties.

The following example uses an AnnotatedRegion<SystemUiOverlayStyle> to set the system status bar color and the system navigation bar color.
link

To create a local project with this code sample, run:
flutter create --sample=services.SystemChrome.setSystemUIOverlayStyle.2 mysample 

import 'dart:math' as math;

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

/// Flutter code sample for setting the [SystemUiOverlayStyle] with an [AnnotatedRegion].

void main() => runApp(const SystemOverlayStyleApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        useMaterial3: true,
        brightness: Brightness.light,
      ),
      home: const SystemOverlayStyleExample(),
    );
  }
}

class SystemOverlayStyleExample extends StatefulWidget {
  const SystemOverlayStyleExample({super.key});

  @override
  State<SystemOverlayStyleExample> createState() =>
      _SystemOverlayStyleExampleState();
}

class _SystemOverlayStyleExampleState extends State<SystemOverlayStyleExample> {
  final math.Random _random = math.Random();
  SystemUiOverlayStyle _currentStyle = SystemUiOverlayStyle.light;

  void _changeColor() {
    final Color color = Color.fromRGBO(
      _random.nextInt(255),
      _random.nextInt(255),
      _random.nextInt(255),
      1.0,
    );
    setState(() {
      _currentStyle = SystemUiOverlayStyle.dark.copyWith(
        statusBarColor: color,
        systemNavigationBarColor: color,
      );
    });
  }

  @override
  Widget build(BuildContext context) {
    return AnnotatedRegion<SystemUiOverlayStyle>(
      value: _currentStyle,
      child: Scaffold(
        body: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: <Widget>[
            Padding(
              padding: const EdgeInsets.all(16.0),
              child: Text(
                'SystemUiOverlayStyle Sample',
                style: Theme.of(context).textTheme.titleLarge,
              ),
            ),
            Expanded(
              child: Center(
                child: ElevatedButton(
                  onPressed: _changeColor,
                  child: const Text('Change Color'),
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

See also:

Implementation

static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
  if (_pendingStyle != null) {
    // The microtask has already been queued; just update the pending value.
    _pendingStyle = style;
    return;
  }
  if (style == _latestStyle) {
    // Trivial success: no microtask has been queued and the given style is
    // already in effect, so no need to queue a microtask.
    return;
  }
  _pendingStyle = style;
  scheduleMicrotask(() {
    assert(_pendingStyle != null);
    if (_pendingStyle != _latestStyle) {
      SystemChannels.platform.invokeMethod<void>(
        'SystemChrome.setSystemUIOverlayStyle',
        _pendingStyle!._toMap(),
      );
      _latestStyle = _pendingStyle;
    }
    _pendingStyle = null;
  });
}