DOCSEARCHbyAlgolia
Submit Docs

Capacitor Safe Area Plugin

repository·master·Indexed 41 days ago

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

A Capacitor plugin version 8.0.1 that provides access to device safe area insets to avoid notches and status bars, and patches the safe area for older versions of Chromium. It includes functionality to manage system bar styles and visibility via setSystemBarsStyle(), showSystemBars(), and hideSystemBars().

Tokens
1.4K
Snippets
6
Records
7
Agent score
2%

What's inside Capacitor Safe Area

  1. Configure the SafeArea plugin in capacitor.config.ts

    master

    You can configure initial system bar styles and Android-specific viewport behavior in your capacitor.config.ts file under the plugins object using the SafeArea key.

    Configuration Options

    KeyTypeDefaultDescription
    statusBarStyleSystemBarsStylenullThe initial style applied to the status bar.
    navigationBarStyleSystemBarsStylenullThe initial style applied to the navigation bar. Note: On iOS, the home indicator color is managed automatically by the OS and cannot be styled.
    detectViewportFitCoverChangesbooleantrueAndroid Only. If true, the plugin detects changes to the viewport-fit=cover meta tag. Setting this to false may cause UI issues if the webview content doesn't handle safe area insets correctly.
    initialViewportFitCoverbooleantrueAndroid Only. Sets the initial value for viewport-fit=cover to prevent layout jumps. The plugin will eventually sync with the actual value if detectViewportFitCoverChanges is true.
    offsetForKeyboardInsetBugbooleanN/ADeprecated. This is no longer necessary as the fix is included by default.
    const config: CapacitorConfig = {
  plugins: {
    SafeArea: {
      statusBarStyle: 'DARK',
      navigationBarStyle: 'LIGHT',
      detectViewportFitCoverChanges: true,
      initialViewportFitCover: true
    }
  }
};

  2. Use the SafeArea plugin

    master

    The SafeArea plugin provides access to device safe area insets. You can import the SafeArea instance directly from the package to call its methods. The plugin is registered using @capacitor/core and supports web implementations via dynamic import.

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

// Example usage (methods depend on the SafeAreaPlugin definition)
// const insets = await SafeArea.getInsets();

  3. Set system bar styles with setSystemBarsStyle()

    master

    Use setSystemBarsStyle() to change the appearance of the status bar or navigation bar content.

    Options

    • style: The SystemBarsStyle to apply ('DARK', 'LIGHT', or 'DEFAULT'). Defaults to 'DEFAULT'.
    • type: The SystemBarsType to target ('STATUS_BAR' or 'NAVIGATION_BAR'). If null, the style is applied to both bars. Note: On iOS, the home indicator cannot be styled manually.

    SystemBarsStyle Enum

    • Dark: Light content on a dark background.
    • Light: Dark content on a light background.
    • Default: Style follows the device appearance (Dark mode = light content, Light mode = dark content).
    import { SafeArea } from '@capacitor-community/safe-area';

// Set both status and navigation bars to Dark style
await SafeArea.setSystemBarsStyle({ style: 'DARK' });

// Set only the status bar to Light style
await SafeArea.setSystemBarsStyle({ 
  style: 'LIGHT', 
  type: 'STATUS_BAR' 
});

  4. Show or hide system bars with showSystemBars() and hideSystemBars()

    master

    Use showSystemBars() and hideSystemBars() to control the visibility of the device's system bars.

    Options

    • type: The SystemBarsType to target ('STATUS_BAR' or 'NAVIGATION_BAR'). If null, the action is applied to both bars.

    SystemBarsType Enum

    • StatusBar: The top status bar on both Android and iOS.
    • NavigationBar: The navigation bar/gesture bar on Android, or the home indicator on iOS.
    import { SafeArea } from '@capacitor-community/safe-area';

// Hide both status bar and navigation bar
await SafeArea.hideSystemBars({ type: null });

// Show only the status bar
await SafeArea.showSystemBars({ type: 'STATUS_BAR' });

  5. Reference: SystemBarsStyle

    master

    Enum defining the visual style of the content within the system bars.

    export enum SystemBarsStyle {
  /** Light system bar content on a dark background. */
  Dark = 'DARK',
  /** For dark system bar content on a light background. */
  Light = 'LIGHT',
  /** The style is based on the device appearance or the underlying content. */
  Default = 'DEFAULT',
}