@capawesome/capacitor-android-edge-to-edge-support

Capacitor plugin to support edge-to-edge display on Android with advanced features like setting the background color of the status bar and navigation bar.

Before	After	Before	After

Attention: Despite its name, this plugin doesn't enable edge-to-edge mode by default. Instead, it preserves the traditional app behavior by applying proper insets to the webview, preventing Android's edge-to-edge changes from affecting apps that haven't been designed to support it.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-android-edge-to-edge-support` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-android-edge-to-edge-support
npx cap sync

Android

Capacitor SystemBars Plugin

Make sure to disable the built-in insets handling of the Capacitor SystemBars plugin in your Capacitor Configuration file:

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

Please note that this plugin is part of the Capacitor core and the insets handling is always enabled by default.

Capacitor Keyboard Plugin

If you are using the Capacitor Keyboard plugin, make sure to set the resizeOnFullScreen property to false (default) in your Capacitor Configuration file:

{
  "plugins": {
    "Keyboard": {
      "resizeOnFullScreen": false
    }
  }
}

Otherwise, the web view will be resized to fit the screen, which may cause issues with this plugin, see this comment.

Configuration

Examples

In capacitor.config.json:

{
  "plugins": {
    "EdgeToEdge": {
      "backgroundColor": "#ffffff",
      "navigationBarColor": "#000000",
      "statusBarColor": "#ffffff"
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-android-edge-to-edge-support" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    EdgeToEdge: {
      backgroundColor: "#ffffff",
      navigationBarColor: "#000000",
      statusBarColor: "#ffffff",
    },
  },
};

export default config;

Usage

The plugin only needs to be installed. It applies insets to the web view to support edge-to-edge display on Android. The plugin also provides a method to set the background color of the status bar and navigation bar. It's recommended to use this method in combination with the SystemBars plugin.

import { EdgeToEdge } from '@capawesome/capacitor-android-edge-to-edge-support';
import { SystemBars, SystemBarsStyle } from '@capacitor/core';

const enable = async () => {
  await EdgeToEdge.enable();
};

const disable = async () => {
  await EdgeToEdge.disable();
};

const getInsets = async () => {
  const result = await EdgeToEdge.getInsets();
  console.log('Insets:', result);
};

const setDarkStyle = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
  await EdgeToEdge.setBackgroundColor({ color: '#000000' });
};

const setLightStyle = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Light });
  await EdgeToEdge.setBackgroundColor({ color: '#FFFFFF' });
};

API

• disable()
• enable()
• getInsets()
• setBackgroundColor(...)
• setNavigationBarColor(...)
• setStatusBarColor(...)
• Interfaces

disable()

disable() => Promise<void>

Disable the edge-to-edge mode.

Only available on Android.

Since: 7.2.0

enable()

enable() => Promise<void>

Enable the edge-to-edge mode.

Only available on Android.

Since: 7.2.0

getInsets()

getInsets() => Promise<GetInsetsResult>

Return the insets that are currently applied to the webview.

Only available on Android.

Returns: Promise<GetInsetsResult>

Since: 7.2.0

setBackgroundColor(...)

setBackgroundColor(options: SetBackgroundColorOptions) => Promise<void>

Set the background color of the status bar and navigation bar.

Only available on Android.

Since: 7.0.0

setNavigationBarColor(...)

setNavigationBarColor(options: SetNavigationBarColorOptions) => Promise<void>

Set the background color of the navigation bar area.

Only available on Android.

Since: 8.0.0

setStatusBarColor(...)

setStatusBarColor(options: SetStatusBarColorOptions) => Promise<void>

Set the background color of the status bar area.

Only available on Android.

Since: 8.0.0

Interfaces

GetInsetsResult

SetBackgroundColorOptions

SetNavigationBarColorOptions

SetStatusBarColorOptions

FAQ

What about Capacitor 8's built-in edge-to-edge support?

Capacitor 8 introduced native edge-to-edge functionality through the internal SystemBars plugin. While this covers many common scenarios, this plugin addresses additional edge cases that aren't yet fully resolved in the Capacitor core implementation. We plan to deprecate this plugin once all edge cases are properly handled in Capacitor core.

Is this plugin compatible with Capacitor's SystemBars API?

Yes, this plugin is partially compatible with the new SystemBars API introduced in Capacitor 8. For example, methods like setStyle() from the SystemBars API are supported and can be used alongside this plugin without conflicts.

Changelog

See CHANGELOG.md.

License

See LICENSE.