setSystemUIOverlayStyle static method
- 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.
AppBar
to set the system status bar color and
the system navigation bar color.
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.
AnnotatedRegion<SystemUiOverlayStyle>
to set
the system status bar color and the system navigation bar color.
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:
- AppBar.systemOverlayStyle, a convenient property for declaratively setting the style of the system overlays.
- AnnotatedRegion, the widget used to place a
SystemUiOverlayStyle
into the layer tree.
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;
});
}