@molecule/app-status-bar

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.

Status bar customization interface for molecule.dev.

Framework-agnostic core for the mobile status bar through a swappable StatusBarProvider: setStyle (light/dark icons), setBackgroundColor, show/hide, overlay mode (setOverlaysWebView), state/height queries, one-shot configure, and theme presets + applyPreset.

Quick Start

import {
  getCapabilities,
  hasProvider,
  setBackgroundColor,
  setStyle,
} from '@molecule/app-status-bar'

async function matchStatusBarToTheme(dark: boolean): Promise<void> {
  if (!hasProvider()) return // web/desktop: browsers have no status bar
  await setStyle(dark ? 'light' : 'dark') // icon color over your header
  const caps = await getCapabilities()
  if (caps.canSetBackgroundColor) {
    await setBackgroundColor(dark ? '#0f172a' : '#ffffff')
  }
}

Type

native

Installation

npm install @molecule/app-status-bar @molecule/app-bond @molecule/app-i18n

API

Interfaces

StatusBarCapabilities

Status bar capabilities

interface StatusBarCapabilities {
  /** Whether status bar control is supported */
  supported: boolean
  /** Whether background color can be set */
  canSetBackgroundColor: boolean
  /** Whether style can be set */
  canSetStyle: boolean
  /** Whether visibility can be controlled */
  canSetVisibility: boolean
  /** Whether overlay mode can be set */
  canSetOverlay: boolean
  /** Whether animations are supported */
  supportsAnimation: boolean
}

StatusBarConfig

Status bar configuration

interface StatusBarConfig {
  /** Background color (hex or named color) */
  backgroundColor?: string
  /** Content style (dark/light icons and text) */
  style?: StatusBarStyle
  /** Whether status bar is visible */
  visible?: boolean
  /** Whether content overlays status bar */
  overlaysWebView?: boolean
}

StatusBarProvider

Status bar provider interface

interface StatusBarProvider {
  /**
   * Set background color
   * @param color - Hex color (e.g., '#ffffff') or named color
   */
  setBackgroundColor(color: string): Promise<void>

  /**
   * Set content style (dark/light icons)
   * @param style - Status bar style
   */
  setStyle(style: StatusBarStyle): Promise<void>

  /**
   * Show the status bar
   * @param animation - Animation type (iOS)
   */
  show(animation?: StatusBarAnimation): Promise<void>

  /**
   * Hide the status bar
   * @param animation - Animation type (iOS)
   */
  hide(animation?: StatusBarAnimation): Promise<void>

  /**
   * Set whether content overlays the status bar
   * @param overlay - Whether to overlay
   */
  setOverlaysWebView(overlay: boolean): Promise<void>

  /**
   * Get current status bar state
   */
  getState(): Promise<StatusBarState>

  /**
   * Get status bar height
   */
  getHeight(): Promise<number>

  /**
   * Apply multiple settings at once
   * @param config - Status bar configuration
   */
  configure(config: StatusBarConfig): Promise<void>

  /**
   * Get the platform's status bar capabilities.
   * @returns The capabilities indicating which status bar features are supported.
   */
  getCapabilities(): Promise<StatusBarCapabilities>
}

StatusBarState

Status bar state

interface StatusBarState {
  /** Whether status bar is visible */
  visible: boolean
  /** Current background color */
  backgroundColor: string
  /** Current content style */
  style: StatusBarStyle
  /** Whether content overlays status bar */
  overlaysWebView: boolean
  /** Status bar height in pixels */
  height: number
}

Types

StatusBarAnimation

Status bar animation type

type StatusBarAnimation = 'none' | 'fade' | 'slide'

StatusBarStyle

Status bar style (content color)

type StatusBarStyle = 'dark' | 'light' | 'default'

Functions

applyPreset(preset)

Apply a named preset configuration to the status bar.

function applyPreset(preset: 'dark' | 'light' | 'transparent' | 'hidden'): Promise<void>

• preset — The preset name: 'light', 'dark', 'transparent', or 'hidden'.

Returns: A promise that resolves when the preset is applied.

configure(config)

Apply multiple status bar settings at once (color, style, visibility, overlay).

function configure(config: StatusBarConfig): Promise<void>

• config — The status bar configuration to apply.

Returns: A promise that resolves when all settings are applied.

getCapabilities()

Get the platform's status bar capabilities.

function getCapabilities(): Promise<StatusBarCapabilities>

Returns: The capabilities indicating which status bar features are supported.

getHeight()

Get the current status bar height in pixels.

function getHeight(): Promise<number>

Returns: The status bar height in pixels.

getProvider()

Get the current status bar provider.

function getProvider(): StatusBarProvider

Returns: The active StatusBarProvider instance.

getSafeAreaInsetTop()

Get the CSS environment variable value for the top safe area inset, with a fallback of 0px. Useful for positioning content below the status bar.

function getSafeAreaInsetTop(): string

Returns: A CSS env(safe-area-inset-top) expression string.

getState()

Get the current status bar state including visibility, color, style, and height.

function getState(): Promise<StatusBarState>

Returns: The full status bar state.

hasProvider()

Check if a status bar provider has been registered.

function hasProvider(): boolean

Returns: Whether a StatusBarProvider has been bonded.

hide(animation)

Hide the status bar with an optional animation.

function hide(animation?: StatusBarAnimation): Promise<void>

• animation — Animation type for hiding: 'none', 'fade', or 'slide' (iOS only).

Returns: A promise that resolves when the status bar is hidden.

isLightColor(color)

Check if a color is light (for determining text color)

function isLightColor(color: string): boolean

• color — Hex color

Returns: Whether light color.

matchColor(color)

Make status bar match a color (auto-detect style)

function matchColor(color: string): Promise<void>

• color — Hex color to match

setBackgroundColor(color)

Set the status bar background color.

function setBackgroundColor(color: string): Promise<void>

• color — Hex color (e.g., '#ffffff') or named color.

Returns: A promise that resolves when the color is set.

setDarkTheme(backgroundColor)

Set status bar for dark theme

function setDarkTheme(backgroundColor?: string): Promise<void>

• backgroundColor — Optional background color (default: black)

setLightTheme(backgroundColor)

Set status bar for light theme

function setLightTheme(backgroundColor?: string): Promise<void>

• backgroundColor — Optional background color (default: white)

setOverlaysWebView(overlay)

Set whether app content overlays (renders behind) the status bar.

function setOverlaysWebView(overlay: boolean): Promise<void>

• overlay — Whether content should extend behind the status bar.

Returns: A promise that resolves when the overlay setting is applied.

setProvider(provider)

Set the status bar provider.

function setProvider(provider: StatusBarProvider): void

• provider — StatusBarProvider implementation to register.

setStyle(style)

Set the status bar content style (dark or light icons and text).

function setStyle(style: StatusBarStyle): Promise<void>

• style — The content style: 'dark' for dark icons, 'light' for light icons, or 'default'.

Returns: A promise that resolves when the style is set.

show(animation)

Show the status bar with an optional animation.

function show(animation?: StatusBarAnimation): Promise<void>

• animation — Animation type for showing: 'none', 'fade', or 'slide' (iOS only).

Returns: A promise that resolves when the status bar is shown.

Constants

presets

Preset status bar configurations

const presets: {
  readonly light: {
    readonly backgroundColor: '#ffffff'
    readonly style: StatusBarStyle
    readonly visible: true
    readonly overlaysWebView: false
  }
  readonly dark: {
    readonly backgroundColor: '#000000'
    readonly style: StatusBarStyle
    readonly visible: true
    readonly overlaysWebView: false
  }
  readonly transparent: {
    readonly backgroundColor: '#00000000'
    readonly style: StatusBarStyle
    readonly visible: true
    readonly overlaysWebView: true
  }
  readonly hidden: { readonly visible: false }
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• Every accessor THROWS until setProvider() is called. The one prebuilt bond is @molecule/app-status-bar-react-native; web has no bond — browsers expose no status bar (theme-color meta is the closest web concept and is app code, not this package). Gate on hasProvider().

• Capability-gate everything beyond style/visibility. setBackgroundColor and setOverlaysWebView are Android-only in the react-native bond (silent no-ops on iOS), and getHeight() returns 0 on iOS — use safe-area insets for layout, never this value.

• setStyle('light') means LIGHT ICONS (for dark backgrounds), not a light bar — the naming trips everyone; pair style changes with the header color they sit over (or use applyPreset).

• getState() reflects what this provider last set, not changes made elsewhere (e.g. a navigation library managing the bar itself).

Translations

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