capacitor-plugin-safe-area

To install the plugin, run the following commands in your project terminal:

npm install capacitor-plugin-safe-area@latest
npx cap sync

To use safe area insets with TailwindCSS, use the tailwindcss-safe-area-capacitor plugin. This allows you to use utility classes like pb-safe to handle bottom safe areas automatically.

Example integration in a React component:

import { useEffect } from 'react';
import { SafeArea } from 'capacitor-plugin-safe-area';

const App = () => {
    useEffect(() => {
        (async function(){
            const { insets } = await SafeArea.getSafeAreaInsets();
            for (const [key, value] of Object.entries(insets)) {
                document.documentElement.style.setProperty(
                    `--safe-area-inset-${key}`,
                    `${value}px`,
                );
            }
        })()
    }, []);

    return (
        <div className="pb-safe toolbar">
            <div>....</div>
        </div>
    );
}

To react to device orientation changes or other events that alter the safe area, use addListener with the 'safeAreaChanged' event. It is recommended to call removeAllListeners() before setting up new listeners to avoid duplicates.

import { SafeArea } from 'capacitor-plugin-safe-area';

// Clear existing listeners
await SafeArea.removeAllListeners();

// Listen for changes
await SafeArea.addListener('safeAreaChanged', data => {
  const { insets } = data;
  for (const [key, value] of Object.entries(insets)) {
    document.documentElement.style.setProperty(
      `--safe-area-inset-${key}`,
      `${value}px`,
    );
  }
});

On Android, you can control the immersive mode of the navigation bar. Note that these methods are not implemented on iOS. When setting immersive mode, the status bar background is automatically set to transparent.

• setImmersiveNavigationBar(options): Enables immersive mode.
• unsetImmersiveNavigationBar(options): Disables immersive mode.

import { SafeArea } from 'capacitor-plugin-safe-area';

// Enable immersive mode
await SafeArea.setImmersiveNavigationBar({ statusBarStyle: 'dark' });

// Disable immersive mode
await SafeArea.unsetImmersiveNavigationBar();

Use getSafeAreaInsets() to retrieve the padding required to avoid notches and system bars, and getStatusBarHeight() to get the specific height of the status bar.

Common practice is to map these insets to CSS custom properties so they can be used in your styles.

import { SafeArea } from 'capacitor-plugin-safe-area';

// Get insets and apply to CSS variables
SafeArea.getSafeAreaInsets().then(({ insets }) => {
  for (const [key, value] of Object.entries(insets)) {
    document.documentElement.style.setProperty(
      `--safe-area-inset-${key}`,
      `${value}px`,
    );
  }
});

// Get status bar height
SafeArea.getStatusBarHeight().then(({ statusBarHeight }) => {
  console.log(statusBarHeight);
});

The plugin uses the following data structures for safe area information:

SafeArea

• top: number
• right: number
• bottom: number
• left: number

SafeAreaInsets

• insets: SafeArea

Options for controlling the navigation and status bar:

NavigationBarOptions

• statusBarBg: string (status bar background color, default is transparent)
• statusBarStyle: StatusbarStyle

StatusbarStyle

• 'light': Light style
• 'dark': Dark style

Retrieve the current device's safe area insets (top, right, bottom, and left) to ensure your UI does not overlap with system notches, status bars, or navigation bars. Returns a SafeAreaInsets object containing a SafeArea object with numeric values for each side.

const { insets } = await SafeAreaPlugin.getSafeAreaInsets();
console.log(insets.top, insets.right, insets.bottom, insets.left);

Retrieve the height of the mobile status bar in pixels. Returns a StatusBarInfo object containing the statusBarHeight property.

const { statusBarHeight } = await SafeAreaPlugin.getStatusBarHeight();

To use the SafeArea plugin in your Capacitor project, import the SafeArea constant from the package. This object provides access to all safe area related methods defined in the plugin's interface.

import { SafeArea } from 'capacitor-plugin-safe-area';

// Example usage:
// const insets = await SafeArea.getSafeAreaInsets();

Removes all active native listeners registered via this plugin. Use this to clean up all event subscriptions at once.

await SafeAreaPlugin.removeAllListeners();

Subscribe to the safeAreaChanged event to react dynamically when the device's safe area insets change (e.g., during device rotation or when system UI elements appear/disappear). The listener receives a SafeAreaInsets object.

const handler = await SafeAreaPlugin.addListener('safeAreaChanged', (data) => {
  console.log('New insets:', data.insets);
});

// To clean up later:
// await handler.remove();