Skip to content
Tutorials Center
My learning

Topics

Lesson 52 of 73 ยท Platform integration

Wakelock, Orientation Lock and System UI

Keep the screen awake with wakelock_plus, lock orientation with SystemChrome, hide system bars for immersive mode, style the status bar, and restore settings safely.

Some screens need to change how the device behaves while they are open. A recipe app should not dim the screen while you cook. A video player wants landscape and no status bar. A camera or game may want portrait only. These are system-level settings, so they live outside the widget tree, and that has one important consequence: they stay set until you change them back. Most bugs in this area are about forgetting to restore a setting when the screen closes.

Real vs stand-in. The Dart is real and read-only, because the site cannot change a phone's screen timeout or orientation. The live examples are JavaScript stand-ins of the bookkeeping: a wakelock shared by several screens, and a stack of orientation preferences that restores correctly.

Keeping the screen awake

The wakelock_plus package asks the OS not to dim or lock the screen.

DART
import 'package:wakelock_plus/wakelock_plus.dart';

class RecipeScreen extends StatefulWidget {
  const RecipeScreen({super.key});
  @override
  State<RecipeScreen> createState() => _RecipeScreenState();
}

class _RecipeScreenState extends State<RecipeScreen> {
  @override
  void initState() {
    super.initState();
    WakelockPlus.enable();
  }

  @override
  void dispose() {
    WakelockPlus.disable();   // always give the screen timeout back
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => const Scaffold(body: Center(child: Text('Step 1: preheat the oven')));
}

You can also call WakelockPlus.toggle(enable: true) and read await WakelockPlus.enabled. No permission is needed on Android; on iOS it uses the idle timer. A wakelock burns battery by keeping the display lit, so use it only while the user is actively reading or watching, and release it when they leave or the app goes to the background.

The plugin holds one boolean, not a counter. If two screens both enable it and one of them disposes, the lock turns off for the screen that still needs it. The stand-in shows the problem and a fix.

JS A shared wakelock: boolean versus reference count

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Locking the orientation

SystemChrome (from package:flutter/services.dart) talks to the platform about orientation and system bars.

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

// Portrait only:
await SystemChrome.setPreferredOrientations([
  DeviceOrientation.portraitUp,
]);

// Landscape only (a game or video):
await SystemChrome.setPreferredOrientations([
  DeviceOrientation.landscapeLeft,
  DeviceOrientation.landscapeRight,
]);

// Restore: pass all the orientations you support (an empty list also unlocks them).
await SystemChrome.setPreferredOrientations(DeviceOrientation.values);

For a whole app locked to portrait, call this once in main() after WidgetsFlutterBinding.ensureInitialized(), and also declare the supported orientations in the native projects (android:screenOrientation in the manifest, UISupportedInterfaceOrientations in Info.plist). For a single screen, set the preference in initState and restore it in dispose.

Locking has costs. Many users rotate to type or to enlarge content, so a blanket portrait lock can hurt accessibility. On large screens (tablets, foldables and desktop windows) Android and iPadOS increasingly ignore orientation locks, and Android 16 ignores them for apps on large displays, so design a layout that survives rotation (responsive layouts). To react to the current orientation without locking anything, read MediaQuery.orientationOf(context) or use OrientationBuilder.

JS Restoring orientation with a preference stack

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Hiding the system bars: immersive mode

For full-screen video, photos or games, hide the status and navigation bars:

DART
await SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);   // bars hide, swipe from the edge shows them briefly
// Other modes:
//   SystemUiMode.immersive      bars hide until the user swipes
//   SystemUiMode.leanBack       bars hide until the user taps (Android)
//   SystemUiMode.edgeToEdge     app draws behind transparent bars (the modern default)
//   SystemUiMode.manual, overlays: [SystemUiOverlay.top]   choose which bars stay

// leaving:
await SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);

When the app draws edge to edge, content can sit under the notch, status bar or gesture bar. Keep important widgets away from those areas with SafeArea (SafeArea and friends), and handle the keyboard separately with MediaQuery.viewInsetsOf(context).

Styling the status and navigation bars

To make the icons readable against your background, set an overlay style. The cleanest way is AnnotatedRegion, which applies the style while the widget is on screen:

DART
AnnotatedRegion<SystemUiOverlayStyle>(
  value: SystemUiOverlayStyle.dark.copyWith(
    statusBarColor: Colors.transparent,
    systemNavigationBarColor: Colors.white,
  ),
  child: Scaffold(/* ... */),
)

SystemUiOverlayStyle.dark means dark icons (for light backgrounds), and light means light icons. An AppBar sets this for you from its theme; add the region when a screen has no app bar, such as a full-bleed image header. statusBarColor is ignored on newer Android versions that draw edge to edge and on iOS, where the icon style is what you control (themes and dark mode).

Putting it together: a reader screen

DART
class _ReaderState extends State<Reader> {
  @override
  void initState() {
    super.initState();
    WakelockPlus.enable();
    SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
  }

  @override
  void dispose() {
    WakelockPlus.disable();
    SystemChrome.setPreferredOrientations(DeviceOrientation.values);
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);
    super.dispose();
  }
  // build ...
}

Pair every call in initState with its undo in dispose. If the user can leave with a gesture that skips your cleanup (such as the app being killed), the OS resets the settings, but a normal navigation will not.

Common mistakes

  • Forgetting to undo. The next screen inherits a landscape lock or hidden bars.
  • Using a plain wakelock from several screens. Wrap it in a counter.
  • Locking orientation for the whole app out of habit. Check tablets and accessibility first.
  • Putting content under the system bars. Use SafeArea in edge-to-edge mode.
  • Not awaiting. These calls return futures. Await them in main() before runApp if the first frame depends on them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a screen that enables the wakelock disable it in dispose?

    System settings are not scoped to widgets, so you must undo them yourself.
  2. 2. How do you unlock orientation again after locking to portrait?

    Pass DeviceOrientation.values (or the list your app supports) to allow rotation again.
  3. 3. What does SystemUiMode.immersiveSticky do?

    It is meant for video, photo and game screens that need the whole display.
  4. 4. Which widget applies a status bar icon style only while a screen is visible?

    AnnotatedRegion tells the engine which overlay style the region wants.

Summary

  • WakelockPlus.enable() keeps the screen on; disable it in dispose, and use a counter if several screens may need it.
  • SystemChrome.setPreferredOrientations locks rotation; restore it when leaving, and prefer responsive layouts over blanket locks.
  • setEnabledSystemUIMode hides or reveals system bars; use SafeArea for edge-to-edge drawing.
  • Use AnnotatedRegion<SystemUiOverlayStyle> to match status bar icons to your background.

Next: Generating and Previewing PDFs, File Pickers