@whjvenyl/safe-area

Safe Area

@capacitor-community/safe-area

A plugin to expose the safe area insets from the native iOS/Android device to your web project.

Maintainers

Maintainer	GitHub	Social
Kevin Pacheco	PolymorphiK	@k_pacheco10

Installation

Soon(TM) - As long as the official repo isn't published this serves as a placeholder.

Configuration

iOS: Soon(TM)

For Android, register plugin in your main activity.

import com.getcapacitor.community.safearea.SafeAreaPlugin;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
  
	this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
	  add(SafeAreaPlugin.class);
	}});
  }
}

Here is a bonus tip, to get full screen mode use this in your main activity. Requires Android 28+

@Override
public void onResume() {
super.onResume();

// Requires API 28+
this.getWindow().getAttributes().layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES;

View decorView = this.getWindow().getDecorView();

decorView.setSystemUiVisibility(
		View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
				// Set the content to appear under the system bars so that the
				// content doesn't resize when the system bars hide and show.
				| View.SYSTEM_UI_FLAG_LAYOUT_STABLE
				| View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
				| View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
				// Hide the nav bar and status bar
				| View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
				| View.SYSTEM_UI_FLAG_FULLSCREEN);
}

To change the Android build version, change the minSdkVersion to at least 28 in the variables.gradle file.
For more information please see Android's immersive, and short edges documentation.

Usage

Register the plugin via the entry file of your project.

// Register Capacitor Plugin...
import '@capacitor-community/safe-area';

It is strongly recomended that you use the SafeAreaController as it makes it super easy to use the plugin :)

import { SafeAreaController } from '@capacitor-community/safe-area';

// Initialize the controller.
SafeAreaController.load();

// Gets the insets object
// Shape
/*
 {
     top: number,
     bottom: number,
     right: number,
     left: number,
 }
 */
SafeAreaController.getInsets();

// Use this to listen for changes in the insets.
// i.e. when the device is rotated
SafeAreaController.addListener((insets) => {
    
});

// Use this to force the plugin to invoke the event
// Example, after you add a listener perhaps you invoke refresh
// to get the most up-to-date inset values.
SafeAreaController.refresh();

// Uninitialize the controller when you don't need it anymore.
SafeAreaController.unload();

Once the SafeAreaController has been loaded, it will inject CSS variables for you to use in your style sheets.

/* styling for every case Web, iOS, and/or Android */
.myContainer {
	paddingTop: max(1.5rem, val(--safe-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--safe-area-inset-left));
	paddingRight: max(1.5rem, val(--safe-area-inset-right));
	paddingBottom: val(--safe-area-inset-bottom);
}

/* If you need Android specific stying */
.myContainerForAndroidOnly {
	paddingTop: max(1.5rem, val(--android-safe-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--android-safe-area-inset-left));
	paddingRight: max(1.5rem, val(--android-safe-area-inset-right));
	paddingBottom: val(--android-safe-area-inset-bottom);
}

/* If you need iOS specific styling */
.myContainerForIOSOnly {
	paddingTop: max(1.5rem, val(--ios-safe-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--ios-safe-area-inset-left));
	paddingRight: max(1.5rem, val(--ios-safe-area-inset-right));
	paddingBottom: val(--ios-safe-area-inset-bottom);
}

This can also be used with the styles attribute in something like React.js for example.

// This div will grow to cover the area of the cutout
// this would be at the very top.
<div
	style={{
		height: "var(--safe-area-inset-top)",
		backgroundColor: "#12005e"
	}}>
</div>

React - SafeAreaInsetsProvider

Here is a component that can be used by React.js developers. This handles everything for you via the SafeAreaController. There is a hook you can use as well called useSafeAreaInsetsState which will return a JSON object with top, bottom, right, and left number properties.

import * as React from 'react';
import { SafeAreaController } from '@capacitor-community/safe-area';

const StateContext = React.createContext();

export const useSafeAreaInsetsState = () => {
	const context = React.useContext(StateContext);

	if(context === undefined)
		throw new Error("Cannot use 'useSafeAreaInsetsState' outside of a SafeAreaInsetsProvider!");
	
	return context;
}

const SafeAreaInsetsProvider = ({children}) => {
	const [state, setState] = React.useState({
		top: 0,
		bottom: 0,
		right: 0,
		left: 0
	});

	React.useState(() => {
		SafeAreaController.addListener((insets) => {
			setState(insets);
		});

		SafeAreaController.load();

		return () => {
			SafeAreaController.removeAllListeners();
			SafeAreaController.unload();
		}
	}, []);

	return (
		<StateContext.Provider value={state}>
			{children}
		</StateContext.Provider>
	)
};

export default SafeAreaInsetsProvider;

You can then use this provider ideally in the index file of your project.

ReactDOM.render(
	<React.StrictMode>
		<SafeAreaInsetsProvider>
			<App />
		</SafeAreaInsetsProvider>
	</React.StrictMode>,
	document.getElementById('root')
);