@squareetlabs/capacitor-android-edge-to-edge

Capacitor 6 and 7 plugin to support edge-to-edge display on Android using WindowCompat.enableEdgeToEdge().

Features

• ✅ Edge-to-edge display support on Android
• ✅ Safe area insets handling
• ✅ Automatic layout adjustment for system bars
• ✅ Keyboard aware - adjusts layout when keyboard is visible
• ✅ Status bar & navigation bar color configuration
• ✅ Visual protection - light/dark icon appearance
• ✅ Immersive mode - fullscreen support for games and videos
• ✅ Navigation bar contrast control
• ✅ Keyboard animations support

Installation

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

Android

This plugin enables edge-to-edge display on Android using WindowCompat.enableEdgeToEdge() as recommended by the Android documentation.

Configuration in capacitor.config.ts:

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

const config: CapacitorConfig = {
  plugins: {
    EdgeToEdge: {
      // Disable edge-to-edge when gesture navigation is detected
      disableEdgeToEdgeForGesture: true
    }
  }
};

export default config;

Important: 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.

Compatibility

This plugin is compatible with:

• Capacitor 6.x
• Capacitor 7.x

Android

• Minimum SDK: API level 22
• Uses WindowCompat.enableEdgeToEdge() for Android R+ (API 30+)
• Falls back to system UI flags for older Android versions

Usage

The plugin automatically applies edge-to-edge mode when the plugin loads. It applies insets to the web view to support edge-to-edge display on Android.

import { EdgeToEdge } from '@squareetlabs/capacitor-android-edge-to-edge';

// Enable edge-to-edge mode (called automatically on load)
const enable = async () => {
  await EdgeToEdge.enable();
};

// Disable edge-to-edge mode
const disable = async () => {
  await EdgeToEdge.disable();
};

// Get current insets (safe area)
const getInsets = async () => {
  const result = await EdgeToEdge.getInsets();
  console.log('Insets:', result);
  // { top: 24, bottom: 48, left: 0, right: 0 }
};

// Configure status bar appearance (light icons)
await EdgeToEdge.setStatusBarAppearance({ light: true });

// Set status bar color (semi-transparent black)
await EdgeToEdge.setStatusBarColor({ color: '#80000000' });

// Set navigation bar color (transparent)
await EdgeToEdge.setNavigationBarColor({ color: '#00000000' });

// Configure navigation bar contrast (translucent vs transparent)
await EdgeToEdge.setNavigationBarContrastEnforced({ enforce: false });

// Enter immersive mode (fullscreen)
await EdgeToEdge.enterImmersiveMode();

// Exit immersive mode
await EdgeToEdge.exitImmersiveMode();

// Enable keyboard animations
await EdgeToEdge.setKeyboardAnimation({ enabled: true });

// Configure all settings at once
await EdgeToEdge.configure({
  lightStatusBar: true,
  lightNavigationBar: true,
  statusBarColor: '#80000000',
  navigationBarColor: '#00000000',
  enforceContrast: false,
  immersive: false
});

// For gesture navigation (recommended)
await EdgeToEdge.configureForGestureNavigation({
  lightStatusBar: true,
  lightNavigationBar: true,
  statusBarColor: '#F54927',
  immersive: false
});

// Check if device is using gesture navigation
const result = await EdgeToEdge.checkGestureNavigation();
console.log('Is gesture navigation:', result.isGestureNavigation);

// Disable edge-to-edge for gesture navigation
await EdgeToEdge.setConfiguration({
  disableEdgeToEdgeForGesture: true
});

API

Methods

enable()

Enable the edge-to-edge mode.

Returns: Promise<void>

Only available on Android.

disable()

Disable the edge-to-edge mode.

Returns: Promise<void>

Only available on Android.

getInsets()

Return the insets that are currently applied to the webview.

Returns: Promise<GetInsetsResult>

Only available on Android.

setStatusBarAppearance(options)

Set the status bar appearance (light or dark icons).

Param	Type
options	SetStatusBarAppearanceOptions

Returns: Promise<void>

Only available on Android.

setNavigationBarAppearance(options)

Set the navigation bar appearance (light or dark icons).

Param	Type
options	SetNavigationBarAppearanceOptions

Returns: Promise<void>

Only available on Android.

setStatusBarColor(options)

Set the status bar color.

Param	Type
options	SetStatusBarColorOptions

Returns: Promise<void>

Only available on Android.

setNavigationBarColor(options)

Set the navigation bar color.

Param	Type
options	SetNavigationBarColorOptions

Returns: Promise<void>

Only available on Android.

setNavigationBarContrastEnforced(options)

Control whether the navigation bar should have contrast enforced.

Param	Type
options	SetNavigationBarContrastEnforcedOptions

Returns: Promise<void>

Only available on Android.

enterImmersiveMode()

Enter immersive fullscreen mode (hide system bars). Recommended for games, videos, and other immersive experiences.

Returns: Promise<void>

Only available on Android.

exitImmersiveMode()

Exit immersive fullscreen mode (show system bars).

Returns: Promise<void>

Only available on Android.

setImmersiveMode(options)

Enter or exit immersive mode.

Param	Type
options	SetImmersiveModeOptions

Returns: Promise<void>

Only available on Android.

isImmersiveMode()

Check if currently in immersive mode.

Returns: Promise<IsImmersiveModeResult>

Only available on Android.

setKeyboardAnimation(options)

Enable or disable keyboard animation. This provides smooth animations when the keyboard appears/disappears.

Param	Type
options	SetKeyboardAnimationOptions

Returns: Promise<void>

Only available on Android.

configure(options)

Apply comprehensive edge-to-edge configuration with all settings.

Param	Type
options	ConfigureOptions

Returns: Promise<void>

Only available on Android.

checkGestureNavigation()

Check if the device is using gesture navigation.

Returns: Promise<CheckGestureNavigationResult>

Only available on Android.

setConfiguration(options)

Set plugin configuration options.

Param	Type
options	SetConfigurationOptions

Returns: Promise<void>

Only available on Android.

Interfaces

GetInsetsResult

Prop	Type	Description
bottom	number	The bottom inset that was applied to the webview. Only available on Android.
left	number	The left inset that was applied to the webview. Only available on Android.
right	number	The right inset that was applied to the webview. Only available on Android.
top	number	The top inset that was applied to the webview. Only available on Android.

SetStatusBarAppearanceOptions

Prop	Type	Description
light	boolean	true for light icons (dark background), false for dark icons (light background)

SetNavigationBarAppearanceOptions

Prop	Type	Description
light	boolean	true for light icons (dark background), false for dark icons (light background)

SetStatusBarColorOptions

Prop	Type	Description
color	string	Color in ARGB format (e.g., "#FF000000" for opaque black, "#80000000" for semi-transparent black)

SetNavigationBarColorOptions

Prop	Type	Description
color	string	Color in ARGB format (e.g., "#FF000000" for opaque black, "#80000000" for semi-transparent black)

SetNavigationBarContrastEnforcedOptions

Prop	Type	Description
enforce	boolean	true to enforce contrast (translucent), false for transparent

SetImmersiveModeOptions

Prop	Type	Description
enter	boolean	true to enter immersive mode, false to exit

IsImmersiveModeResult

Prop	Type	Description
immersive	boolean	Whether the app is currently in immersive mode

SetKeyboardAnimationOptions

Prop	Type	Description
enabled	boolean	true to enable keyboard animation, false to disable

ConfigureOptions

Prop	Type	Description
lightStatusBar	boolean	true for light status bar icons (dark background), false for dark icons (light background). Default: false
lightNavigationBar	boolean	true for light navigation bar icons (dark background), false for dark icons (light background). Default: false
statusBarColor	string	Status bar color in ARGB format (e.g., "#FF000000" for opaque black)
navigationBarColor	string	Navigation bar color in ARGB format (e.g., "#FF000000" for opaque black)
enforceContrast	boolean	true to enforce navigation bar contrast (translucent), false for transparent. Default: true
immersive	boolean	true to enter immersive mode (hide system bars). Default: false

CheckGestureNavigationResult

Prop	Type	Description
isGestureNavigation	boolean	Whether the device is using gesture navigation

SetConfigurationOptions

Prop	Type	Description
disableEdgeToEdgeForGesture	boolean	Disable edge-to-edge when gesture navigation is enabled

License

MIT