capacitor-plugin-safe-area

a capacitor plugin to get SafeArea info on Android and IOS, latest version is support for Capacitor v7.

Version Support

• v5.0.0 support Capacitor v8
• v4.0.0 support Capacitor v7
• v3.0.0 support Capacitor v6
• v2.0.0 support Capacitor v5
• v1.0.0 support Capacitor v4
• v0.0.1 support Capacitor v3

I'm very glad if the plugin helped you, please give it a star

Install

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

Usage

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

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

SafeArea.getStatusBarHeight().then(({ statusBarHeight }) => {
  console.log(statusBarHeight, 'statusbarHeight');
});

await SafeArea.removeAllListeners();

// when safe-area changed
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`,
    );
  }
});

Use with TailwindCSS

Use TailwindCSS with the plugin: https://github.com/mahyarmirrashed/tailwindcss-safe-area-capacitor

For more usage, please refer to the plugin repo

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

import type {FC} from 'react';

const App = () => {
    useEffect(() => {
        (async function(){
            const safeAreaData = await SafeArea.getSafeAreaInsets();
            const {insets} = safeAreaData;
            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>
    )
}
export default App;

API

• getSafeAreaInsets()
• getStatusBarHeight()
• setImmersiveNavigationBar(...)
• unsetImmersiveNavigationBar(...)
• addListener('safeAreaChanged', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

getSafeAreaInsets()

getSafeAreaInsets() => Promise<SafeAreaInsets>

Get mobile SafeArea info

Returns: Promise<SafeAreaInsets>

---

getStatusBarHeight()

getStatusBarHeight() => Promise<StatusBarInfo>

Get mobile statusbar height

Returns: Promise<StatusBarInfo>

---

setImmersiveNavigationBar(...)

setImmersiveNavigationBar(options?: Pick<NavigationBarOptions, "statusBarStyle"> | undefined) => Promise<void>

Set navigation bar immersive on Android , statusbar background is always set to transparent, not implemented on IOS

Param	Type
options	Pick<NavigationBarOptions, 'statusBarStyle'>

---

unsetImmersiveNavigationBar(...)

unsetImmersiveNavigationBar(options?: NavigationBarOptions | undefined) => Promise<void>

unset navigation bar immersive on Android , not implemented on IOS

Param	Type
options	NavigationBarOptions

---

addListener('safeAreaChanged', ...)

addListener(event: 'safeAreaChanged', listenerFunc: (data: SafeAreaInsets) => void) => Promise<PluginListenerHandle>

Event listener when safe-area changed

Param	Type
event	'safeAreaChanged'
listenerFunc	(data: SafeAreaInsets) => void

Returns: Promise<PluginListenerHandle>

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all native listeners for this plugin

---

Interfaces

SafeAreaInsets

Prop	Type
insets	SafeArea

SafeArea

Prop	Type
top	number
right	number
bottom	number
left	number

StatusBarInfo

Prop	Type
statusBarHeight	number

NavigationBarOptions

Prop	Type	Description
statusBarBg	string	statusbar background color, default is transparent
statusBarStyle	StatusbarStyle	statusbar style

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Type Aliases

Pick

From T, pick a set of properties whose keys are in the union K

{ [P in K]: T[P]; }

Enums

StatusbarStyle

Members	Value
Light	'light'
Dark	'dark'