# capacitor-plugin-safe-area
#### a capacitor plugin to get SafeArea info on Android and IOS, latest version is support for Capacitor v7.
### 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
```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](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()`](#getsafeareainsets)
* [`getStatusBarHeight()`](#getstatusbarheight)
* [`setImmersiveNavigationBar(...)`](#setimmersivenavigationbar)
* [`unsetImmersiveNavigationBar(...)`](#unsetimmersivenavigationbar)
* [`addListener('safeAreaChanged', ...)`](#addlistenersafeareachanged-)
* [`removeAllListeners()`](#removealllisteners)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)
### getSafeAreaInsets()
```typescript
getSafeAreaInsets() => Promise
```
Get mobile SafeArea info
**Returns:** Promise<SafeAreaInsets>
--------------------
### getStatusBarHeight()
```typescript
getStatusBarHeight() => Promise
```
Get mobile statusbar height
**Returns:** Promise<StatusBarInfo>
--------------------
### setImmersiveNavigationBar(...)
```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'> |
--------------------
### unsetImmersiveNavigationBar(...)
```typescript
unsetImmersiveNavigationBar(options?: NavigationBarOptions | undefined) => Promise
```
unset navigation bar immersive on Android , not implemented on IOS
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| **`options`** | NavigationBarOptions |
--------------------
### addListener('safeAreaChanged', ...)
```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>
--------------------
### removeAllListeners()
```typescript
removeAllListeners() => Promise
```
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' |