github.com/capacitor-community/safe-area @v8.0.1

Safe Area

@capacitor-community/safe-area

Capacitor Plugin that patches the safe area for older versions of Chromium

Introduction

On web and iOS the safe area insets work perfectly fine out of the box¹. That is, on these platforms the env(safe-area-inset-*) CSS variables will have the correct values by default. On Android (in combination with Capacitor), however, those CSS variables will not always have the correct values when Edge-to-Edge mode is enabled. So we need to work some magic in order to achieve the desired behavior. This plugin does that by detecting the Chromium version a user has installed. If a user has a Chromium version lower than 140, this plugin makes sure the webview gets the safe area as a padding. The env(safe-area-inset-*) values will be set to 0px. That means for the Chromium webview versions with a bug, the developer doesn't have to worry about safe area insets at all. For all other versions, the developer should handle the safe area insets just as he would on web or iOS (by using the env(safe-area-inset-*) CSS variables). In short you can think of this plugin as a polyfill for older webview versions.

[!NOTE]

¹ As with all (regular) web applications, you still need to tell the browser to scale the viewport as so to fill the device display by setting a viewport meta value like so:

html <meta name="viewport" content="viewport-fit=cover" />

More info on the Mozilla website about setting the <meta name="viewport"> and using CSS env().

Installation

For Capacitor v8

npm install @capacitor-community/safe-area
npx cap sync

For Capacitor v7

npm install @capacitor-community/safe-area@^7.0.0
npx cap sync

Usage

The plugin itself is enabled automatically. Additionally, you should enable native edge-to-edge mode in your MainActivity like so:

Java:

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        EdgeToEdge.enable(this); // enable edge-to-edge mode
    }
}

Kotlin:

class MainActivity : BridgeActivity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge() // enable edge-to-edge mode
    }
}

Additionally, this plugin provides helper methods to style the system bars and its content. You can find the API docs here.

Setup

This plugin might conflict with some of your existing setup. Please go through the following steps, to ensure proper functioning of this plugin.

If you're installing this plugin into a fresh Capacitor setup, you can probably skip most - if not all - of these steps.

@capacitor/keyboard

The keyboard plugin by Capacitor has a configuration prop called resizeOnFullScreen. You should either omit it or set it to false. Otherwise it would interfere with the logic in this plugin. The bug that the Capacitor team is trying to fix with that prop is already accounted for in this plugin. So you should be good to go a don't worry about it at all.

@capacitor/status-bar

When using @capacitor-community/safe-area, you should uninstall @capacitor/status-bar. Instead you can use the System Bars API this plugin provides.

adjustMarginsForEdgeToEdge setting

Capacitor provides a setting called adjustMarginsForEdgeToEdge. It's advised to either omit this value or set it to disable to prevent interference. This plugin already does a similar thing when it detects a broken webview.

windowOptOutEdgeToEdgeEnforcement

If you've set windowOptOutEdgeToEdgeEnforcement in your AndroidManifest.xml, you should probably remove it. It has been deprecated and shouldn't be necessary when using this plugin anyways.

Extending BridgeWebViewClient and calling setWebViewClient

If you're running Capacitor v7 and have extended the BridgeWebViewClient by calling bridge.setWebViewClient in your code, you should update your code so that it extends SafeAreaWebViewClient instead. If you're running Capacitor v8 you do not have to worry about this at all.

Other safe area plugins

If you've installed any other safe area plugin, you should remove them to prevent interference.

Examples of these are: @capawesome/capacitor-android-edge-to-edge-support, capacitor-plugin-safe-area and @aashu-dubey/capacitor-statusbar-safe-area.

Just make sure to uninstall those and you should be good to go.

Earlier versions of this plugin

Alpha versions of this plugin (@capacitor-community/safe-area@alpha) are deprecated and usage of those versions is advised against. Please migrate to a latest channel instead. Differences between the older versions and the newer versions are outlined here.

Capacitor v8

If you're running Capacitor v8, you should set the following in your capacitor.config.json:

{
  "plugins": {
    "SystemBars": {
      "insetsHandling": "disable"
    }
  }
}

Differences between this plugin, system-bars and status-bar

The main differences are as follows:

² Chromium versions < 140 do not correctly report safe area insets. So we need a workaround for those webviews. This can be done using padding or custom CSS vars. This plugin advocates for using padding. As it seems to be the least breaking behavior.

³ The webview has a known bug to not resize the webview when the keyboard is shown.

⁴ The webview has another known bug to not properly report bottom insets when the keyboard is shown. Which will be fixed in Chromium 144

⁵ The Capacitor team themselves are also working on a similar solution by means of a CapacitorSystemBars plugin. It's still a work in progress though. Currently that PR is merged as is and in a beta state. Their design/approach philosophy also deviates from the one in this plugin.

FAQ

Do I need this plugin?

You probably do! Apps targeting Android sdk version 36 will automatically be in edge to edge mode on a device running Android 16+. This means you should properly support safe area insets. This seemingly works just fine. However Chromium versions < 140 have a bug that causes the webview to receive incorrect values (0px). This plugin works around that by adding a padding to the webview for those devices. As a bonus, this plugin resizes the webview upon keyboard visibility changes, something that also isn't standard.

Why doesn't Capacitor take care of this out of the box?

They can and they should. They tried / are trying actually. But IMHO their approach isn't ready for production (yet). The differences between their approach and the one of this plugin are outlined here. I try to adhere to their coding style and I am actively providing feedback to the Capacitor team in hopes they will - sometime - upstream this plugin into th