@capacitor-community/safe-area v6.0.0-alpha.8

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.

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:

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

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

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

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:

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

Or maybe you want to do something like this:

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

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(...)
• disable(...)
• Interfaces

enable(...)

enable(options: { config: Config; }) => Promise<void>

disable(...)

disable(options: { config: Config; }) => Promise<void>

Interfaces

Config

Configuration

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

Examples

In capacitor.config.json:

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

In capacitor.config.ts:

/// <reference types="@capacitor-community/safe-area" />

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;