cordova-plugin-edge-to-edge

A robust Cordova plugin designed to handle Android 15 (API 35+) edge-to-edge enforcement, display cutouts (notches), and system bar behaviors.

It automatically resolves the "blank safe area" and WebView offset issues, ensuring your Cordova application renders in true full-screen.

Features

• Drop-in Solution: Automatically applies the edge-to-edge fix on application start (onload="true"), No JavaScript configuration is required for the basic fix.
• Display Cutout Support: Renders content safely behind camera notches and punch-holes.
• Advanced Insets API: Optionally retrieve accurate Safe Area, System Gestures, and Rounded Corners metrics.
• Immersive Mode Control: Dynamically show or hide system bars (status bar and navigation bar).
• Software Keyboard (IME) Detection: Real-time detection of keyboard visibility and height for layout adjustments.

Supported Platforms

• Android (API 28+ for basic cutout support, optimized for API 35+)

🎉 View all plugin release notes

• 👉 Releases notes

Installation

Install the plugin via Cordova CLI:

cordova plugin add cordova-plugin-edge-to-edge

Usage

By default, the plugin initializes automatically when the Android application boots.

It forces the WebView to ignore system window limits (FLAG_LAYOUT_NO_LIMITS), makes system bars transparent, and applies the SHORT_EDGES cutout mode.

For most applications, simply installing the plugin is enough.

Optional JavaScript API

For advanced control, the plugin exposes an optional JavaScript API under window.EdgeToEdge.

1. getSafeAreaInsets(successCallback, errorCallback)

Retrieves comprehensive metrics about the device's screen boundaries, including safe areas, gesture zones, and hardware rounded corners.

window.EdgeToEdge.getSafeAreaInsets(function(insets) {
    console.log("Safe Area Top: " + insets.top);
    console.log("Safe Area Bottom: " + insets.bottom);
    
    // Check if running in Cordova 15 (Android 15 Edge-to-Edge enforced)
    if (insets.isCordova15) {
        document.body.style.paddingTop = insets.top + 'px';
    }
}, function(error) {
    console.error(error);
});

Response Payload Example:

{
  "screen": {
    "width": 411,
    "height": 891,
    "widthPx": 1080,
    "heightPx": 2340
  },
  "top": 48,
  "bottom": 34,
  "left": 0,
  "right": 0,
  "systemGestures": {
    "top": 0,
    "bottom": 34,
    "left": 20,
    "right": 20
  },
  "roundedCorners": {
    "topLeft": 32,
    "topRight": 32,
    "bottomLeft": 32,
    "bottomRight": 32
  },
  "isCordova15": true
}

2. setImmersiveMode(options, successCallback, errorCallback)

Dynamically hides or shows the system bars (status bar and navigation bar). When hidden, system bars can be temporarily revealed by swiping from the edge.

// Hide system bars
window.EdgeToEdge.setImmersiveMode({ isImmersive: true }, onSuccess, onError);

// Show system bars
window.EdgeToEdge.setImmersiveMode({ isImmersive: false }, onSuccess, onError);

3. setCutoutMode(options, successCallback, errorCallback)

Adjusts how the window behaves around the display cutout (notch).

• shortEdges (Default): Content renders into the cutout area on the short edges of the display.
• never: Content never renders into the cutout area, potentially pushing the WebView down.
• always: Content is always allowed to extend into the cutout areas.
• default: Standard system behavior.

window.EdgeToEdge.setCutoutMode({ mode: 'shortEdges' }, onSuccess, onError);

4. getKeyboardState(successCallback, errorCallback)

Detects if the software keyboard (IME) is currently open and retrieves its height in pixels.

window.EdgeToEdge.getKeyboardState(function(state) {
    if (state.isVisible) {
        console.log("Keyboard height in pixels: " + state.heightPx);
        // Push your input fields up
    }
}, onError);

5. enableEdgeToEdge(successCallback, errorCallback)

Manually re-enables the edge-to-edge layout if it was previously disabled.

window.EdgeToEdge.enableEdgeToEdge(onSuccess, onError);

6. disableEdgeToEdge(successCallback, errorCallback)

Reverts the window layout limits to the Android default, respecting system boundaries and pushing content below the notch.

window.EdgeToEdge.disableEdgeToEdge(onSuccess, onError);

7. Event

document.addEventListener('edge.orientation.changed', function(event) {
    console.log("Screen rotated to: " + event.orientation);
    
    // Immediately fetch the new safe area insets to update UI margins
    if (window.EdgeToEdge) {
        window.EdgeToEdge.getSafeAreaInsets(function(insets) {
            console.log("New Insets after rotation: ", insets);
            
            // Example: If in landscape, the notch might now be on the left
            // document.body.style.paddingLeft = insets.left + 'px';
            // document.body.style.paddingTop = insets.top + 'px';
        }, function(error) {
            console.error(error);
        });
    }
}, false);

References & Related Projects

The layout behaviors and inset calculation logic implemented in this plugin are based on official guidelines and shared architecture from related projects:

• Android Developers: Control the system UI
• cordova-plugin-admob-nextgen — Shares the core inset calculation and Cordova environment detection logic to ensure robust compatibility.

License

This project is licensed under the MIT License.