Molecule.dev

← All @molecule/* packages · App templates

@molecule/app-status-bar-react-native

Provider bond · status-bar · App (browser) · v1.0.1 · Apache-2.0

React Native status bar provider

npm install @molecule/app-status-bar-react-native

npm · Source on GitHub · Implements @molecule/app-status-bar

How it works

@molecule/app-status-bar-react-native is a provider bond on the app (browser) side: it implements the status-bar core interface (@molecule/app-status-bar) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setProvider, setStyle } from '@molecule/app-status-bar'
import { provider } from '@molecule/app-status-bar-react-native'

setProvider(provider)
await setStyle('light') // light text over a dark header

Reference

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

React Native status bar provider for molecule.dev.

Implements the StatusBarProvider interface from @molecule/app-status-bar using React Native's StatusBar API: bar style, visibility, background color, and translucency.

Quick Start

import { setProvider, setStyle } from '@molecule/app-status-bar'
import { provider } from '@molecule/app-status-bar-react-native'

setProvider(provider)
await setStyle('light') // light text over a dark header

Type

provider

Installation

npm install @molecule/app-status-bar-react-native @molecule/app-i18n @molecule/app-status-bar react-native

API

Interfaces

ReactNativeStatusBarConfig

Configuration for the React Native status bar provider.

interface ReactNativeStatusBarConfig {
  /**
   * Initial background color.
   */
  initialBackgroundColor?: string

  /**
   * Initial bar style.
   * @default 'default'
   */
  initialStyle?: 'dark' | 'light' | 'default'

  /**
   * Whether to use animations for changes.
   * @default true
   */
  animated?: boolean
}

Functions

createReactNativeStatusBarProvider(config)

Creates a React Native status bar provider backed by react-native StatusBar.

function createReactNativeStatusBarProvider(config?: ReactNativeStatusBarConfig): StatusBarProvider
  • config — Optional provider configuration.

Returns: A StatusBarProvider implementation for React Native.

Constants

provider

Default React Native status bar provider.

const provider: StatusBarProvider

Core Interface

Implements @molecule/app-status-bar interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-status-bar'
import { provider } from '@molecule/app-status-bar-react-native'

export function setupNativeStatusBarReactNative(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/app-i18n ^1.0.1
  • @molecule/app-status-bar ^1.0.1
  • react-native >=0.72.0

Runtime Dependencies

  • @molecule/app-i18n

  • @molecule/app-status-bar

  • react-native

  • Android-only surfaces: setBackgroundColor() and setOverlaysWebView() (translucency) are Android APIs — silent no-ops on iOS. Style (light/dark) and visibility work on both platforms.

  • getCapabilities() reports per-platform truthfully: canSetBackgroundColor and canSetOverlay are false on iOS (the Android-only no-op APIs above) and true on Android, so callers can feature-detect instead of trusting a blanket true.

  • getHeight() returns 0 on iOS (StatusBar.currentHeight is Android-only) — use safe-area insets for layout, not this value.

  • getState() reflects what THIS provider last set (locally tracked), not values changed elsewhere (e.g. by a navigation library's own status-bar handling).

  • initialStyle/initialBackgroundColor config are applied to the native bar at provider setup (best-effort, fire-and-forget): a configured initialStyle calls setBarStyle on both platforms, and initialBackgroundColor calls setBackgroundColor on Android only (the API is a no-op on iOS). Unset knobs are left untouched, so the OS / navigation library keeps control of them.

Translations

Translation strings are provided by @molecule/app-locales-status-bar.