CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ionic-native--status-bar

Ionic Native StatusBar Plugin - Manage the appearance of the native status bar

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Status Bar

The Ionic Native StatusBar Plugin provides Angular/TypeScript wrapper functionality to manage the appearance and behavior of the native status bar in mobile applications. It offers methods to control status bar visibility, styling (light/dark content), background colors, and overlay behavior for Android, iOS, and Windows platforms.

Package Information

  • Package Name: @ionic-native/status-bar
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ionic-native/status-bar
  • Required Plugin: cordova-plugin-statusbar
  • Plugin Installation: cordova plugin add cordova-plugin-statusbar
  • Platforms: Android, iOS, Windows

Core Imports

import { StatusBar } from '@ionic-native/status-bar/ngx';

For Angular module registration (app.module.ts):

import { StatusBar } from '@ionic-native/status-bar/ngx';

@NgModule({
  providers: [
    StatusBar
  ]
})
export class AppModule { }

Basic Usage

import { Component } from '@angular/core';
import { StatusBar } from '@ionic-native/status-bar/ngx';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html'
})
export class HomePage {
  constructor(private statusBar: StatusBar) {}

  ionViewDidEnter() {
    // Let status bar overlay webview for immersive experience
    this.statusBar.overlaysWebView(true);

    // Set status bar to white background
    this.statusBar.backgroundColorByHexString('#ffffff');

    // Use dark text for light background
    this.statusBar.styleDefault();
  }
}

Capabilities

Note: All StatusBar methods are synchronous and execute immediately.

Status Bar Visibility Control

Control whether the status bar is visible or hidden.

/**
 * Whether the StatusBar is currently visible or not.
 */
isVisible: boolean;

/**
 * Hide the StatusBar
 */
hide(): void;

/**
 * Show the StatusBar  
 */
show(): void;

Overlay Configuration

Configure whether the status bar overlays the main app view.

/**
 * Set whether the status bar overlays the main app view. The default
 * is true.
 *
 * @param doesOverlay Whether the status bar overlays the main app view.
 */
overlaysWebView(doesOverlay: boolean): void;

Status Bar Styling

Set the status bar appearance for different background colors.

/**
 * Use the default statusbar (dark text, for light backgrounds)
 */
styleDefault(): void;

/**
 * Use the lightContent statusbar (light text, for dark backgrounds)
 */
styleLightContent(): void;

/**
 * Use the blackTranslucent statusbar (light text, for dark backgrounds)
 */
styleBlackTranslucent(): void;

/**
 * Use the blackOpaque statusbar (light text, for dark backgrounds)
 */
styleBlackOpaque(): void;

Background Color Configuration

Set the status bar background color using named colors or hex values.

/**
 * Set the status bar to a specific named color. Valid options:
 * black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown.
 *
 * iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.
 *
 * @param colorName The name of the color (from above)
 */
backgroundColorByName(colorName: string): void;

/**
 * Set the status bar to a specific hex color (CSS shorthand supported!).
 *
 * iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.
 *
 * @param hexString The hex value of the color.
 */
backgroundColorByHexString(hexString: string): void;

Usage Examples

Setting Status Bar Colors

import { StatusBar } from '@ionic-native/status-bar/ngx';

constructor(private statusBar: StatusBar) {}

setLightTheme() {
  // For light themes - disable overlay for color changes on iOS
  this.statusBar.overlaysWebView(false);
  this.statusBar.backgroundColorByHexString('#ffffff');
  this.statusBar.styleDefault(); // Dark text
}

setDarkTheme() {
  // For dark themes - disable overlay for color changes on iOS  
  this.statusBar.overlaysWebView(false);
  this.statusBar.backgroundColorByName('black');
  this.statusBar.styleLightContent(); // Light text
}

setImmersiveMode() {
  // For immersive/full-screen experience
  this.statusBar.overlaysWebView(true);
  this.statusBar.styleLightContent();
}

Conditional Status Bar Management

import { Platform } from '@ionic/angular';
import { StatusBar } from '@ionic-native/status-bar/ngx';

constructor(
  private platform: Platform,
  private statusBar: StatusBar
) {}

async initializeApp() {
  await this.platform.ready();
  
  if (this.platform.is('cordova')) {
    // Show status bar on app launch
    this.statusBar.show();
    
    // Configure based on platform
    if (this.platform.is('ios')) {
      this.statusBar.overlaysWebView(false);
      this.statusBar.styleDefault();
    } else if (this.platform.is('android')) {
      this.statusBar.backgroundColorByHexString('#000000');
      this.statusBar.styleLightContent();
    }
  }
}

Platform-Specific Notes

iOS

  • Call overlaysWebView(false) before setting background colors to enable color changes
  • Status bar style changes are immediate
  • Supports all named colors and hex color values

Android

  • Background color changes work with overlay mode enabled or disabled
  • Status bar styling affects system UI appearance
  • Color changes may require specific Android API levels

Windows

  • Limited styling options compared to iOS and Android
  • Basic show/hide functionality is fully supported
  • Color customization support varies by Windows version

Type Definitions

/**
 * StatusBar plugin class extending IonicNativePlugin
 * Injectable Angular service for status bar management
 */
declare class StatusBar {
  /**
   * Whether the StatusBar is currently visible or not
   */
  isVisible: boolean;
  
  /**
   * Set whether the status bar overlays the main app view
   */
  overlaysWebView(doesOverlay: boolean): void;
  
  /**
   * Use the default statusbar (dark text, for light backgrounds)
   */
  styleDefault(): void;
  
  /**
   * Use the lightContent statusbar (light text, for dark backgrounds)
   */
  styleLightContent(): void;
  
  /**
   * Use the blackTranslucent statusbar (light text, for dark backgrounds)
   */
  styleBlackTranslucent(): void;
  
  /**
   * Use the blackOpaque statusbar (light text, for dark backgrounds)
   */
  styleBlackOpaque(): void;
  
  /**
   * Set the status bar to a specific named color
   */
  backgroundColorByName(colorName: string): void;
  
  /**
   * Set the status bar to a specific hex color
   */
  backgroundColorByHexString(hexString: string): void;
  
  /**
   * Hide the StatusBar
   */
  hide(): void;
  
  /**
   * Show the StatusBar
   */
  show(): void;
}

docs

index.md

tile.json