capacitor-plugin-safe-area

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

$3

- [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

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

Usage

`typescript
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

`tsx
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 (



)
}
export default App;
`

API

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




$3

`typescript
getSafeAreaInsets() => Promise
`

Get mobile SafeArea info

Returns: Promise<SafeAreaInsets>

--------------------




$3

`typescript
getStatusBarHeight() => Promise
`

Get mobile statusbar height

Returns: Promise<StatusBarInfo>

--------------------




$3

`typescript
setImmersiveNavigationBar(options?: Pick | undefined) => Promise
`

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

| Param | Type |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| options | Pick<NavigationBarOptions, 'statusBarStyle'> |

--------------------




$3

`typescript
unsetImmersiveNavigationBar(options?: NavigationBarOptions | undefined) => Promise
`

unset navigation bar immersive on Android , not implemented on IOS

| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | NavigationBarOptions |

--------------------




$3

`typescript
addListener(event: 'safeAreaChanged', listenerFunc: (data: SafeAreaInsets) => void) => Promise
`

Event listener when safe-area changed

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

Returns: Promise<PluginListenerHandle>

--------------------




$3

`typescript
removeAllListeners() => Promise
`

Remove all native listeners for this plugin

--------------------




$3


#### 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> |




$3


#### Pick

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

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




$3


#### StatusbarStyle

| Members | Value |
| ----------- | -------------------- |
| Light | 'light' |
| Dark` | 'dark' |