0
# Status Bar
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @ionic-native/status-bar
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ionic-native/status-bar`
10
- **Required Plugin**: `cordova-plugin-statusbar`
11
- **Plugin Installation**: `cordova plugin add cordova-plugin-statusbar`
12
- **Platforms**: Android, iOS, Windows
13

14
## Core Imports
15

16
```typescript
17
import { StatusBar } from '@ionic-native/status-bar/ngx';
18
```
19

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

22
```typescript
23
import { StatusBar } from '@ionic-native/status-bar/ngx';
24

25
@NgModule({
26
  providers: [
27
    StatusBar
28
  ]
29
})
30
export class AppModule { }
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { Component } from '@angular/core';
37
import { StatusBar } from '@ionic-native/status-bar/ngx';
38

39
@Component({
40
  selector: 'app-home',
41
  templateUrl: 'home.page.html'
42
})
43
export class HomePage {
44
  constructor(private statusBar: StatusBar) {}
45

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

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

53
    // Use dark text for light background
54
    this.statusBar.styleDefault();
55
  }
56
}
57
```
58

59
## Capabilities
60

61
**Note**: All StatusBar methods are synchronous and execute immediately.
62

63
### Status Bar Visibility Control
64

65
Control whether the status bar is visible or hidden.
66

67
```typescript { .api }
68
/**
69
 * Whether the StatusBar is currently visible or not.
70
 */
71
isVisible: boolean;
72

73
/**
74
 * Hide the StatusBar
75
 */
76
hide(): void;
77

78
/**
79
 * Show the StatusBar  
80
 */
81
show(): void;
82
```
83

84
### Overlay Configuration
85

86
Configure whether the status bar overlays the main app view.
87

88
```typescript { .api }
89
/**
90
 * Set whether the status bar overlays the main app view. The default
91
 * is true.
92
 *
93
 * @param doesOverlay Whether the status bar overlays the main app view.
94
 */
95
overlaysWebView(doesOverlay: boolean): void;
96
```
97

98
### Status Bar Styling
99

100
Set the status bar appearance for different background colors.
101

102
```typescript { .api }
103
/**
104
 * Use the default statusbar (dark text, for light backgrounds)
105
 */
106
styleDefault(): void;
107

108
/**
109
 * Use the lightContent statusbar (light text, for dark backgrounds)
110
 */
111
styleLightContent(): void;
112

113
/**
114
 * Use the blackTranslucent statusbar (light text, for dark backgrounds)
115
 */
116
styleBlackTranslucent(): void;
117

118
/**
119
 * Use the blackOpaque statusbar (light text, for dark backgrounds)
120
 */
121
styleBlackOpaque(): void;
122
```
123

124
### Background Color Configuration
125

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

128
```typescript { .api }
129
/**
130
 * Set the status bar to a specific named color. Valid options:
131
 * black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown.
132
 *
133
 * iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.
134
 *
135
 * @param colorName The name of the color (from above)
136
 */
137
backgroundColorByName(colorName: string): void;
138

139
/**
140
 * Set the status bar to a specific hex color (CSS shorthand supported!).
141
 *
142
 * iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.
143
 *
144
 * @param hexString The hex value of the color.
145
 */
146
backgroundColorByHexString(hexString: string): void;
147
```
148

149
## Usage Examples
150

151
### Setting Status Bar Colors
152

153
```typescript
154
import { StatusBar } from '@ionic-native/status-bar/ngx';
155

156
constructor(private statusBar: StatusBar) {}
157

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

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

172
setImmersiveMode() {
173
  // For immersive/full-screen experience
174
  this.statusBar.overlaysWebView(true);
175
  this.statusBar.styleLightContent();
176
}
177
```
178

179
### Conditional Status Bar Management
180

181
```typescript
182
import { Platform } from '@ionic/angular';
183
import { StatusBar } from '@ionic-native/status-bar/ngx';
184

185
constructor(
186
  private platform: Platform,
187
  private statusBar: StatusBar
188
) {}
189

190
async initializeApp() {
191
  await this.platform.ready();
192
  
193
  if (this.platform.is('cordova')) {
194
    // Show status bar on app launch
195
    this.statusBar.show();
196
    
197
    // Configure based on platform
198
    if (this.platform.is('ios')) {
199
      this.statusBar.overlaysWebView(false);
200
      this.statusBar.styleDefault();
201
    } else if (this.platform.is('android')) {
202
      this.statusBar.backgroundColorByHexString('#000000');
203
      this.statusBar.styleLightContent();
204
    }
205
  }
206
}
207
```
208

209
## Platform-Specific Notes
210

211
### iOS
212
- Call `overlaysWebView(false)` before setting background colors to enable color changes
213
- Status bar style changes are immediate
214
- Supports all named colors and hex color values
215

216
### Android
217
- Background color changes work with overlay mode enabled or disabled
218
- Status bar styling affects system UI appearance
219
- Color changes may require specific Android API levels
220

221
### Windows
222
- Limited styling options compared to iOS and Android
223
- Basic show/hide functionality is fully supported
224
- Color customization support varies by Windows version
225

226
## Type Definitions
227

228
```typescript { .api }
229
/**
230
 * StatusBar plugin class extending IonicNativePlugin
231
 * Injectable Angular service for status bar management
232
 */
233
declare class StatusBar {
234
  /**
235
   * Whether the StatusBar is currently visible or not
236
   */
237
  isVisible: boolean;
238
  
239
  /**
240
   * Set whether the status bar overlays the main app view
241
   */
242
  overlaysWebView(doesOverlay: boolean): void;
243
  
244
  /**
245
   * Use the default statusbar (dark text, for light backgrounds)
246
   */
247
  styleDefault(): void;
248
  
249
  /**
250
   * Use the lightContent statusbar (light text, for dark backgrounds)
251
   */
252
  styleLightContent(): void;
253
  
254
  /**
255
   * Use the blackTranslucent statusbar (light text, for dark backgrounds)
256
   */
257
  styleBlackTranslucent(): void;
258
  
259
  /**
260
   * Use the blackOpaque statusbar (light text, for dark backgrounds)
261
   */
262
  styleBlackOpaque(): void;
263
  
264
  /**
265
   * Set the status bar to a specific named color
266
   */
267
  backgroundColorByName(colorName: string): void;
268
  
269
  /**
270
   * Set the status bar to a specific hex color
271
   */
272
  backgroundColorByHexString(hexString: string): void;
273
  
274
  /**
275
   * Hide the StatusBar
276
   */
277
  hide(): void;
278
  
279
  /**
280
   * Show the StatusBar
281
   */
282
  show(): void;
283
}
284
```