or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

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