Install

npm install @aashu-dubey/capacitor-statusbar-safe-area
npx cap sync

Usage

import { SafeArea } from '@aashu-dubey/capacitor-statusbar-safe-area';

const getStatusBarHeight = async () => {
  const { height } = await SafeArea.getStatusBarHeight();
  return height; // Ex. 29.090909957885742
};

const getSafeAreaInsets = async () => {
  const insets = await SafeArea.getSafeAreaInsets();
  return insets; // Ex. { "bottom":34, "top":47, "right":0, "left":0 }
};

CSS Variables

Package also exposes CSS variables, for that you need to call injectCSSVariables method in your platform.ready() function or whenever app System UI visibility is changed

import { SafeAreaController } from '@aashu-dubey/capacitor-statusbar-safe-area';

const injectSafeAreaVariables = () => {
  SafeAreaController.injectCSSVariables();
};

then you can use them in your CSS files

.myContainer {
  // '--status-bar-height' & '--safe-area-inset-top' would most probably be same
  margin-top: var(--status-bar-height);
}

.myElement {
  padding-top: var(--safe-area-inset-top);
  padding-left: var(--safe-area-inset-left);
  padding-right: var(--safe-area-inset-right);
  padding-bottom: var(--safe-area-inset-bottom);
}

HTML Tag

Other than the above options, The plugin also exports a <safe-area> custom web component.

Register and Use

Register the custom element in your app initialization (e.g. main.ts, app.component.ts, or root component) or only inside the component it's being used:

import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

Then wrap the content you want to apply safe area spacing on with the <safe-area> tag:

<safe-area>
  <!-- Content here -->
</safe-area>

Attributes

There are two attributes, that can be used with the safe-area web component to control it's behaviour, mode & edges.

<safe-area mode="margin" edges="top,left,right"></safe-area>

more details here.

Framework Examples

// your.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

@Component({
  selector: 'app-your-component',
  standalone: true,
  template: `
    <safe-area>
      <!-- Other content -->
    </safe-area>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class YourComponent {}

// your-component.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class YourComponentModule {}

// app.component.ts or your-component.ts
import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

<!-- your.component.html -->
<safe-area>
  <!-- Other content -->
</safe-area>

import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

registerSafeAreaElement();

const MyComponent = () => {
  return <safe-area>{/* Other content */}</safe-area>;
};

import type { SafeAreaHTMLProps } from '@aashu-dubey/capacitor-statusbar-safe-area';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'safe-area': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & SafeAreaHTMLProps;
    }
  }
}

export {};

<script setup lang="ts">
  import { registerSafeAreaElement } from '@aashu-dubey/capacitor-statusbar-safe-area';

  registerSafeAreaElement();
</script>

<template>
  <safe-area>
    <!-- Other content -->
  </safe-area>
</template>

// vite.config.ts > plugins
vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === 'safe-area',
    },
  },
}),

import type { HTMLAttributes, PublicProps } from 'vue';
import type { SafeAreaHTMLProps } from '@aashu-dubey/capacitor-statusbar-safe-area';

type DefineCustomElement<
  ElementType extends HTMLElement,
  SelectedAttributes extends keyof ElementType = keyof ElementType,
> = new () => ElementType & {
  $props: HTMLAttributes & Partial<Pick<ElementType, SelectedAttributes>> & PublicProps;
};

type SafeAreaAttributes = 'mode' | 'edges';

declare module 'vue' {
  interface GlobalComponents {
    'safe-area': DefineCustomElement<SafeAreaHTMLProps, SafeAreaAttributes>;
  }
}

export {};

With SSR

The plugin and its functionalities are client-specific and might throw an error when used on the server side like #10 and #11, so always make sure to access the plugin on the client side only.

Here are some examples for a possible solution to use the plugin in:

• NuxtJs (Vue)
• NextJS (React)

TypeScript / DOM API

The package automatically registers 'safe-area' in HTMLElementTagNameMap. Standard DOM methods like document.querySelector('safe-area') and document.createElement('safe-area') will automatically be typed as SafeAreaElement:

const el = document.querySelector('safe-area'); // typed as SafeAreaElement | null
if (el) {
  el.mode = 'margin';
  el.edges = 'top,bottom';
}

Capacitor version support

API

• getStatusBarHeight()
• getSafeAreaInsets()
• Interfaces

getStatusBarHeight()

getStatusBarHeight() => Promise<{ height: number; }>

Get the Status bar height on Android and iOS, and on Web it returns 0.

Returns: Promise<{ height: number; }>

getSafeAreaInsets()

getSafeAreaInsets() => Promise<SafeAreaInset>

Get the Safe area insets for Android and iOS, and on Web it returns 0 for all.

Returns: Promise<SafeAreaInset>

Interfaces

SafeAreaInset

SafeAreaHTMLProps