@boengli/capacitor-fullscreen

This Capacitor plugin allows you to enable fullscreen mode in your Android app, hiding the system status and navigation bars for a more immersive experience.

Details

The Fullscreen functionality utilizes WindowInsetsControllerCompat to manage immersive mode on Android.

Compatibility

• Plugin version 0.0.20
  This version is updated for Capacitor 8.
  Requires Android 7.0 (API 24) and above and Java 21.

• Plugin version 0.0.19
  This version is updated for Capacitor 7.
  Requires Android 11.0 (API 30) and above and Java 21.

• Plugin version 0.0.18
  Support is now streamlined for Android 11.0 (API 30) and above. Legacy support for earlier Android versions has been dropped.

• Plugin version 0.0.17
  The immersive mode implementation supports Android 8.0 (API 26) and above.

Installation

1. Install npm i @boengli/capacitor-fullscreen
2. If your app overrides androidxCoreVersion in /android/variables.gradle, make sure it is >= 1.17.0
3. npx cap sync android

Configuration

In your capacitor.config.ts:

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

const config: CapacitorConfig = {
  plugins: {
    Fullscreen: {
      activateOnLoad: true, // default — activates immersive mode as soon as the plugin loads
    },
  },
};

Set activateOnLoad: false if you want to control fullscreen manually and only call activateImmersiveMode() from your own code (e.g. on a specific page or user action).

Example Usage

import { Fullscreen } from '@boengli/capacitor-fullscreen';

try {
  await Fullscreen.activateImmersiveMode();
  console.log('Fullscreen enabled');
} catch (error) {
  console.error('Error enabling fullscreen:', error);
}

iOS

You don't need a plugin. Just add this to your Info.plist:

<key>UIStatusBarHidden</key>
<true/>
<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

Function Descriptions

activateImmersiveMode

activateImmersiveMode() => Promise<void>

Activates immersive mode, hiding both the status and navigation bars.

| Param | Type | Description | |-------|--------|-------------| | N/A | N/A | This function does not take any parameters. |

Returns: A Promise that resolves when immersive mode is successfully activated or rejects with an error if it fails.

deactivateImmersiveMode

deactivateImmersiveMode() => Promise<void>

Deactivates immersive mode, restoring visibility to the status and navigation bars.

| Param | Type | Description | |-------|--------|-------------| | N/A | N/A | This function does not take any parameters. |

Returns: A Promise that resolves when immersive mode is successfully deactivated or rejects with an error if it fails.