🐛 View debug infos and change settings via a central overlay for your app.

debug_overlay demo

To add a debug overlay to your app, pass DebugOverlay.builder() to MaterialApp/CupertinoApp/WidgetsApp.builder:

  builder: DebugOverlay.builder(),
  // And other customization...

The debug overlay only works in debug mode and is not included in your widget tree in profile or release mode unless you pass enableOnlyInDebugMode: false.

There are two ways to open the debug overlay:

  • Shake your phone! (You can disable the shake detection by passing showOnShake: false to DebugOverlay.builder.)
  • Call

By default, this overlay includes MediaQueryDebugHelper, PackageInfoDebugHelper, and DeviceInfoDebugHelper.

Debug Helpers

To add a debug helper, you have to register it by calling either of the following two (which accept any widget):

  • DebugOverlay.prependHelper(myDebugHelper) to add it to the front of the list
  • DebugOverlay.appendHelper(myDebugHelper) to add it to the end of the list

Or, if you want to override all currently registered overlays, set DebugOverlay.helpers.value to a list of widgets.


DeviceInfoDebugHelper demo

Displays information obtained from device_info_plus.


´MediaQueryDebugHelper demo

Displays information obtained from MediaQuery.


´LogsDebugHelper demo

Displays logs generated by your app. To use it, follow these steps:

  1. Store its mutable state, e.g., in a global variable:

    final logs = LogCollection();
  2. Register the helper and supply its state, e.g., in main():

    void main() {
      if (kDebugMode) {
  3. When you generate logs, add them to the collection. Except for message, all parameters are optional:

      message: 'My message',
      error: myException,
      stackTrace: myStackTrace,

By default, this only stores the last 50 logs. You can customize this via the maximumSize parameter of LogCollection.

Logs are only stored in debug builds.


´MediaOverridesDebugHelper demo

This allows you to override the theme mode and locale of your app. To use it, follow these steps:

  1. Store its mutable state, e.g., in a global variable:

    final mediaOverrideState = ValueNotifier(MediaOverrideState());
  2. Register the helper and supply its state, e.g., in main():

    void main() {
      if (kDebugMode) {
          // To support overriding locales, this value must be set and should
          // contain the same locales as passed to [MaterialApp.supportedLocales],
          // [CupertinoApp.supportedLocales] or [WidgetsApp.supportedLocales].
          supportedLocales: supportedLocales,
  3. When building your MaterialApp/CupertinoApp/WidgetsApp, wrap it in a ValueListenableBuilder that uses the state from step 1:

      valueListenable: mediaOverrideState,
      builder: (context, overrideState, child) {
        return MaterialApp(
          // You can access overridden values via [overrideState]:
          themeMode: overrideState.themeMode,
          locale: overrideState.locale,
          builder: DebugOverlay.builder(showOnShake: false),
          supportedLocales: supportedLocales,
          // And your other customizations...


PackageInfoDebugHelper demo

Displays information obtained from package_info_plus.


To implement your own debug helper, you can use the provided DebugHelper class for the layout.

If your information can be represented with Flutter's DiagnosticsNode, you can use DiagnosticsBasedDebugHelper which automatically provides filtering. This is also used internally by DeviceInfoDebugHelper, MediaQueryDebugHelper, and PackageInfoDebugHelper.