Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/capacitor-community/safe-area

Capacitor Plugin that exposes the safe area insets from the native iOS/Android device to your web project.
https://github.com/capacitor-community/safe-area

Last synced: 19 days ago
JSON representation

Capacitor Plugin that exposes the safe area insets from the native iOS/Android device to your web project.

Host: GitHub
URL: https://github.com/capacitor-community/safe-area
Owner: capacitor-community
License: mit
Created: 2021-02-04T20:20:42.000Z (almost 4 years ago)
Default Branch: master
Last Pushed: 2024-10-25T08:06:18.000Z (about 2 months ago)
Last Synced: 2024-11-09T22:03:40.659Z (about 1 month ago)
Language: Kotlin
Homepage:
Size: 32.6 MB
Stars: 62
Watchers: 5
Forks: 16
Open Issues: 5
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md

Awesome Lists containing this project

awesome-capacitorjs - @capacitor-community/safe-area - A plugin to expose the safe area insets from the native iOS/Android device to your web project. (Plugins / Community Plugins)

README

Safe Area

@capacitor-community/safe-area

Capacitor Plugin that exposes the safe area insets from the native iOS/Android device to your web project.

## Introduction

On web and iOS the safe area insets work out of the box¹. That is, on these platforms the `env(safe-area-inset-*)` CSS variables will have the correct values by default. On Android (in combination with Capacitor), however, those CSS variables will not have the correct values when Edge-to-Edge mode is enabled. So we need to work some magic in order to have access to the correct values. This plugin does that by detecting the safe area insets on Android, and injecting them as CSS variables to the browser. On web and iOS it will just fallback to the given values (which, again, are working out of the box).

There's one small but important quirck though, since we cannot override the native `env(safe-area-inset-*)` variables, the values are instead written to custom `var(--safe-area-inset-*)` variables.

> [!NOTE]
> ¹ As with all web applications, you still need to enable the use the variables, by telling the browser to use the whole available space on the screen by adding a new viewport meta value:
>
> ```html
>
> ```
>
> More info on the [Mozilla website](https://developer.mozilla.org/en-US/docs/Web/CSS/env#usage)

### Edge-to-Edge

You'll only need access to the safe area insets when you want to display your app edge-to-edge, by drawing your app content behind the system bars. The system bars are the status bar and the navigation bar. See the comparison table below for clarification:

Edge-to-Edge mode:
Disabled
Enabled
Enabled

Safe Area Plugin installed:

N/A.*

Plugin not installed

Plugin installed

Screenshot:

_{*Plugin not needed when not in Edge-to-Edge mode. Because the safe area insets will always be 0px in this mode. So it wouldn't have any effect.}

This plugin, therefore, also provides utilities for styling those system bars and its content. It enables you to set the color of the bars to any color (e.g. black, white or transparent). It also enables you to set the color of the content (i.e. icon color) to either `light` or `dark`.

## Installation

```bash
npm install @capacitor-community/safe-area
npx cap sync
```

## Usage

### Enabling the plugin

This plugin can be enabled either by using the API or by using the Configuration. It's also possible to combine those two.

#### Enable by using the API

```ts
import { SafeArea } from '@capacitor-community/safe-area';

SafeArea.enable({
config: {
customColorsForSystemBars: true,
statusBarColor: '#00000000', // transparent
statusBarContent: 'light',
navigationBarColor: '#00000000', // transparent
navigationBarContent: 'light',
},
});
```

#### Enable by using the Configuration

See the [Configuration documentation below](#examples) for examples.

> [!IMPORTANT]
> If you're enabling this plugin by using the configuration only and not by calling any of the API methods,
> you should still import the plugin like so:
>
> ```ts
> import '@capacitor-community/safe-area';
> ```

### Using the CSS variables

Having enabled the plugin, it will inject the correct safe area insets as CSS variables to the browser. This enables you to use those variables inside your CSS. You're now able to do this for example:

```css
#header {
padding-top: var(--safe-area-inset-top);
}
```

Or maybe you want to do something like this:

```css
#header {
padding-top: calc(var(--safe-area-inset-top) + 1rem);
}
```

> [!IMPORTANT]
> It's important to note that the used CSS variables are `var(--safe-area-inset-*)` and not `env(safe-area-inset-*)`.
> Unfortunately it's not (yet) possible to override the native `env(` variables. So therefore custom variables are injected instead.

### Using the plugin in an SSR environment

This plugin can be used in an SSR environment. But you should manually call `initialize` like so:

```ts
import { initialize } from '@capacitor-community/safe-area';

initialize();
```

Note that this step is only needed for users using this plugin in an SSR environment.

#### Background information on calling `initialize`

Calling `initialize` will set initial safe area values. It will inject `var(--safe-area-inset-*)` CSS variables with the values set to `max(env(safe-area-inset-*), 0px)` as properties to the document root. This makes sure the CSS variables can be used immediately and everywhere. This is especially important for Android when the plugin isn't enabled (yet) and always for web and iOS. Because otherwise - in those cases - `var(--safe-area-inset-*)` won't have any values.

## API

* [`enable(...)`](#enable)
* [`disable(...)`](#disable)
* [Interfaces](#interfaces)

### enable(...)

```typescript
enable(options: { config: Config; }) => Promise
```

| Param | Type |
| ------------- | ------------------------------------------------------ |
| **`options`** | { config: Config; } |

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

### disable(...)

```typescript
disable(options: { config: Config; }) => Promise
```

| Param | Type |
| ------------- | ------------------------------------------------------ |
| **`options`** | { config: Config; } |

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

### Interfaces

#### Config

| Prop | Type | Description | Default |
| ------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| **`customColorsForSystemBars`** | boolean | Flag indicating that you are responsible for drawing the background color for the system bars. If `false` it will fallback to the default colors for the system bars. | true |
| **`statusBarColor`** | string | Specifies the background color of the status bar. Should be in the format `#RRGGBB` or `#AARRGGBB`. Will only have effect if `customColorsForSystemBars` is set to `true`. | '#000000' |
| **`statusBarContent`** | 'light' \| 'dark' | Specifies the color of the content (i.e. icon color) in the status bar. | 'light' |
| **`navigationBarColor`** | string | Specifies the background color of the navigation bar. Should be in the format `#RRGGBB` or `#AARRGGBB`. Will only have effect if `customColorsForSystemBars` is set to `true`. | '#000000' |
| **`navigationBarContent`** | 'light' \| 'dark' | Specifies the color of the content (i.e. icon color) in the navigation bar. | 'light' |
| **`offset`** | number | Specifies the offset to be applied to the safe area insets. This means that if the safe area top inset is 30px, and the offset specified is 10px, the safe area top inset will be exposed as being 40px. Usually you don't need this, but on iOS the safe area insets are mostly offset a little more by itself already. So you might want to compensate for that on Android. It's totally up to you. The offset will be applied if Edge-to-Edge mode is enabled only. | 0 |

## Configuration

For ease of use and speed, these configuration values are available:

| Prop | Type | Description | Default |
| ------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| **`enabled`** | boolean | Flag indicating whether of not the plugin should be enabled from startup. | false |
| **`customColorsForSystemBars`** | boolean | Flag indicating that you are responsible for drawing the background color for the system bars. If `false` it will fallback to the default colors for the system bars. | true |
| **`statusBarColor`** | string | Specifies the background color of the status bar. Should be in the format `#RRGGBB` or `#AARRGGBB`. Will only have effect if `customColorsForSystemBars` is set to `true`. | '#000000' |
| **`statusBarContent`** | 'light' \| 'dark' | Specifies the color of the content (i.e. icon color) in the status bar. | 'light' |
| **`navigationBarColor`** | string | Specifies the background color of the navigation bar. Should be in the format `#RRGGBB` or `#AARRGGBB`. Will only have effect if `customColorsForSystemBars` is set to `true`. | '#000000' |
| **`navigationBarContent`** | 'light' \| 'dark' | Specifies the color of the content (i.e. icon color) in the navigation bar. | 'light' |
| **`offset`** | number | Specifies the offset to be applied to the safe area insets. This means that if the safe area top inset is 30px, and the offset specified is 10px, the safe area top inset will be exposed as being 40px. Usually you don't need this, but on iOS the safe area insets are mostly offset a little more by itself already. So you might want to compensate for that on Android. It's totally up to you. The offset will be applied if Edge-to-Edge mode is enabled only. | 0 |

### Examples

In `capacitor.config.json`:

```json
{
"plugins": {
"SafeArea": {
"enabled": true,
"customColorsForSystemBars": true,
"statusBarColor": '#000000',
"statusBarContent": 'light',
"navigationBarColor": '#000000',
"navigationBarContent": 'light',
"offset": 0
}
}
}
```

In `capacitor.config.ts`:

```ts
///

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
plugins: {
SafeArea: {
enabled: true,
customColorsForSystemBars: true,
statusBarColor: '#000000',
statusBarContent: 'light',
navigationBarColor: '#000000',
navigationBarContent: 'light',
offset: 0,
},
},
};

export default config;
```