Forked from capacitor-plugin-safe-area

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

Version Support

• [x] v5.0.0 support Capacitor v8
• [x] v4.0.0 support Capacitor v7
• [x] v3.0.0 support Capacitor v6
• [x] v2.0.0 support Capacitor v5
• [x] v1.0.0 support Capacitor v4
• [x] 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' |