Remove the debug banner

A tiny but flashy UI detail when running your first Flutter apps can barely be missed: the debug banner on the top right. Questions arise:

• What is the actual purpose?
• Can it be configured or hidden?
• Can we make our own individual banner?

What is the purpose?

There are three supported modes which configure the compilation of a Flutter app. These are called build modes:

• Debug
• Profile
• Release

You probably already know about the main benefits of the Debug build but you may not know that they’re exclusively available for this build mode:

• Hot reload is available
• Compilation times are reduced
• Debugging is enabled

As great as these attributes are for the development process, as problematic would they be if they were enabled in a production build.
Depending on your development process, you may often switch between Debug, Profile and Release modes. To see at a glance whether you are building in Debug mode or not, the banner is displayed (or hidden). Otherwise, you might see behaviors such as poor performance as a problem with your application, rather than an intentional behavior of the build mode.

The official purpose mentioned by flutter.dev is:

"This banner is intended to deter people from complaining that your app is slow when it’s in debug mode. In debug mode, Flutter enables a large number of expensive diagnostics to aid in development, and so performance in debug mode is not representative of what will happen in release mode."

How to remove it

There are good reasons to temporarily or permanently remove it:

• Making screenshots (e. g. for marketing purposes)
• Preventing the banner to cover important parts of the UI during development

Using the respective parameter

The easiest and most obvious way to hide the banner is to use the parameter provided for this purpose. It’s a parameter of the MaterialApp or CupertinoApp and it’s called debugShowCheckedModeBanner.

1class MyApp extends StatelessWidget {
2  @override
3  Widget build(BuildContext context) {
4    return MaterialApp(
5      home: MyHomePage(),
6      debugShowCheckedModeBanner: false,
7    );
8  }
9}

As the name of the parameter suggests, it influences the debug mode builds and hides the banner, which is displayed by default.

Compiling a release build

By compiling a release build of your app, the banner will automatically be hidden. This mode is however not supported on simulators. In order to trigger such a build via CLI, use the following command:

1flutter run --release

Instead of directly running the release build, you can also build your app (e. g. an apk file), which will also create a release build like this:

1flutter build apk

How to create our own banner

What happens under the hood when we trigger a debug build and set debugShowCheckedModeBanner not explicitly to false, is that everything inside the widget tree is wrapped with a CheckedModeBanner.

We can see this inside the WidgetsApp class, that is the basic for both the MaterialApp widget and the CupertinoApp widget:

1if (widget.debugShowCheckedModeBanner && WidgetsApp.debugAllowBannerOverride) {
2  result = CheckedModeBanner(
3    child: result,
4  );
5}

But what is CheckedModeBanner exactly?

Well, the build() function of it says it all:

 1  @override
 2  Widget build(BuildContext context) {
 3    Widget result = child;
 4    assert(() {
 5      result = Banner(
 6        message: 'DEBUG',
 7        textDirection: TextDirection.ltr,
 8        location: BannerLocation.topEnd,
 9        child: result,
10      );
11      return true;
12    }());
13    return result;
14  }

It seems like the CheckedModeBanner itself is nothing more than an a preconfigured Banner widget with the label DEBUG and its location on the top right.

Let’s conclude:

• debugShowCheckedModeBanner is evaluated inside the WidgetsApp, which is the base for MaterialApp and CupertinoApp
• It determines whether everything is wrapped with CheckedModeBanner
• MaterialApp builds one of these by default when running in debug mode
• CheckedModeBanner is nothing else than a configured Banner

Doesn’t that mean that we can directly use the Banner widget and configure it differently for our own purpose?

Let’s try!

1Banner(
2  message: 'This is a test',
3  location: BannerLocation.bottomStart,
4  color: Colors.green,
5  textStyle: TextStyle(fontSize: 9),
6  child: Container(),
7);

We can alter the message, the color, the textStyle and the location. Be aware that too long texts will be clipped, though.

Closing words

The debug banner, as annoying as it can be when making screenshots, has its raison d’être. It drastically reduces the likeliness of situations in which the tester is tricked into thinking it’s a release build with a poor performance.

There are situations, in which it’s more appropriate to hide it. For this purpose, there is a respective parameter.

If one wants to customize the banner (e. g. put the current app version there), it’s possible using the Banner widget.