or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-expo-status-bar

Provides the same interface as the React Native StatusBar API, but with slightly different defaults to work great in Expo environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/expo-status-bar@3.0.x

To install, run

npx @tessl/cli install tessl/npm-expo-status-bar@3.0.0

index.mddocs/

Expo Status Bar

Expo Status Bar provides the same interface as the React Native StatusBar API, but with slightly different defaults to work great in Expo environments. It offers cross-platform status bar management with automatic theming support and improved defaults for Expo managed and bare workflow projects.

Package Information

  • Package Name: expo-status-bar
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install expo-status-bar

Core Imports

import { 
  StatusBar, 
  setStatusBarStyle, 
  setStatusBarHidden,
  setStatusBarBackgroundColor,
  setStatusBarNetworkActivityIndicatorVisible,
  setStatusBarTranslucent,
  StatusBarStyle,
  StatusBarAnimation,
  StatusBarProps
} from "expo-status-bar";

// ColorValue is imported from React Native when needed for function parameters
import { type ColorValue } from "react-native";

For CommonJS:

const { 
  StatusBar, 
  setStatusBarStyle, 
  setStatusBarHidden,
  setStatusBarBackgroundColor,
  setStatusBarNetworkActivityIndicatorVisible,
  setStatusBarTranslucent
} = require("expo-status-bar");

Basic Usage

import React from "react";
import { StatusBar } from "expo-status-bar";

export default function App() {
  return (
    <>
      <StatusBar style="auto" />
      {/* Your app content */}
    </>
  );
}

Architecture

Expo Status Bar consists of three main components:

  • StatusBar Component: React component for declarative status bar configuration
  • Imperative Functions: Direct functions for programmatic status bar control
  • Platform Adapters: Platform-specific implementations with edge-to-edge compatibility (Android), no-op implementations (web), and full functionality (iOS/default)
  • Automatic Theming: Smart defaults that adapt to light/dark mode with 'auto' and 'inverted' style options

Capabilities

Status Bar Component

React component that allows you to configure your status bar without directly calling imperative methods.

/**
 * A component that allows you to configure your status bar without directly calling imperative
 * methods like `setBarStyle`. Multiple StatusBar components can be mounted simultaneously,
 * with props merged in mount order.
 */
function StatusBar(props: StatusBarProps): JSX.Element;

interface StatusBarProps {
  /**
   * Sets the color of the status bar text. Default value is "auto" which
   * picks the appropriate value according to the active color scheme.
   * @default 'auto'
   */
  style?: StatusBarStyle;
  
  /**
   * If the transition between status bar property changes should be
   * animated. Supported for backgroundColor, barStyle and hidden.
   */
  animated?: boolean;
  
  /**
   * If the status bar is hidden.
   */
  hidden?: boolean;
  
  /**
   * The transition effect when showing and hiding the status bar using
   * the hidden prop.
   * @default 'fade'
   * @platform ios
   */
  hideTransitionAnimation?: StatusBarAnimation;
  
  /**
   * If the network activity indicator should be visible.
   * @platform ios
   */
  networkActivityIndicatorVisible?: boolean;
  
  /**
   * The background color of the status bar.
   * @platform android
   */
  backgroundColor?: string;
  
  /**
   * If the status bar is translucent. When translucent is set to true,
   * the app will draw under the status bar. This is the default behaviour in
   * projects created with Expo tools because it is consistent with iOS.
   * @default true
   * @platform android
   */
  translucent?: boolean;
}

Usage Examples:

import { StatusBar } from "expo-status-bar";

// Auto theming (adapts to light/dark mode)
<StatusBar style="auto" />

// Always light content
<StatusBar style="light" />

// Hide with animation
<StatusBar hidden={true} hideTransitionAnimation="slide" />

// Android-specific styling
<StatusBar 
  style="dark" 
  backgroundColor="#ff0000" 
  translucent={false} 
/>

// iOS-specific network indicator
<StatusBar 
  style="auto" 
  networkActivityIndicatorVisible={true} 
/>

Style Configuration

Set the bar style of the status bar programmatically.

/**
 * Set the bar style of the status bar.
 * @param style - The color of the status bar text
 * @param animated - If the transition should be animated
 */
function setStatusBarStyle(style: StatusBarStyle, animated?: boolean): void;

Visibility Control

Toggle visibility of the status bar programmatically.

/**
 * Toggle visibility of the status bar.
 * @param hidden - If the status bar should be hidden
 * @param animation - Animation to use when toggling hidden, defaults to 'none'
 */
function setStatusBarHidden(hidden: boolean, animation?: StatusBarAnimation): void;

Background Color Control

Set the background color of the status bar (Android only).

/**
 * Set the background color of the status bar.
 * @param backgroundColor - The background color of the status bar
 * @param animated - true to animate the background color change, false to change immediately
 * @platform android
 */
function setStatusBarBackgroundColor(backgroundColor: ColorValue, animated?: boolean): void;

Network Activity Indicator

Toggle visibility of the network activity indicator (iOS only).

/**
 * Toggle visibility of the network activity indicator.
 * @param visible - If the network activity indicator should be visible
 * @platform ios
 */
function setStatusBarNetworkActivityIndicatorVisible(visible: boolean): void;

Translucent Control

Set the translucency of the status bar (Android only).

/**
 * Set the translucency of the status bar.
 * @param translucent - Whether the app can draw under the status bar. When true, content will be
 * rendered under the status bar. This is always true on iOS and cannot be changed.
 * @platform android
 */
function setStatusBarTranslucent(translucent: boolean): void;

Types

/**
 * Status bar text color styles with automatic theming support
 */
type StatusBarStyle = 'auto' | 'inverted' | 'light' | 'dark';

/**
 * Animation types for status bar visibility transitions
 */
type StatusBarAnimation = 'none' | 'fade' | 'slide';

/**
 * React Native color value type (from react-native)
 * Used for function parameters that accept various color formats
 */
type ColorValue = string | number;

Platform-Specific Behavior

Android

  • Defaults to translucent={true} for Expo consistency
  • Supports background color and translucent settings
  • Edge-to-edge compatibility with automatic warnings for incompatible operations
  • When edge-to-edge is enabled, backgroundColor and translucent settings are ignored

iOS

  • Supports network activity indicator
  • Supports hide transition animations
  • Status bar is always translucent and cannot be changed

Web

  • All functions are no-op implementations
  • StatusBar component returns null (web doesn't have native status bar)

Edge-to-Edge Compatibility

When edge-to-edge mode is enabled (detected automatically), the package provides helpful warnings:

  • backgroundColor prop: Console warning that backgroundColor is not supported; suggests rendering a view under the status bar instead
  • translucent={false}: Console warning that status bar is always translucent in edge-to-edge mode
  • setStatusBarBackgroundColor(): Console warning that function is not supported
  • setStatusBarNetworkActivityIndicatorVisible(): Console warning that function is not supported
  • setStatusBarTranslucent(): Console warning that function is not supported since status bar is always translucent

These warnings help developers understand when certain features are unavailable due to edge-to-edge constraints.

Automatic Theming

The package provides intelligent theming through special style values:

  • 'auto': Dark status bar in light mode, light status bar in dark mode
  • 'inverted': Light status bar in light mode, dark status bar in dark mode
  • 'light': Always light status bar content
  • 'dark': Always dark status bar content