🧭 rns-statusbar

A modern, lightweight, and high-performance React Native + Expo native module for managing the status bar height and background color across both Android and iOS.
Includes an optional SafeArea wrapper component for simplified layout handling and improved visual consistency.

Built natively using Kotlin (Android) and Swift (iOS) for maximum performance and reliability.

✨ Key Features

• ✅ Dynamic, per-device status bar height retrieval
• ✅ Hex-based status bar background color control
• ✅ Current color getter for runtime queries
• ✅ Simple React hook and SafeArea wrapper component
• ✅ 100% compatible with Expo EAS Build and bare React Native
• ✅ Full TypeScript support (auto-complete and type definitions)

📦 Installation

Using npm

npm install rns-statusbar

Using yarn

yarn add rns-statusbar

⚙️ Expo / EAS Setup

If you use Expo Prebuild / EAS Build, the plugin is automatically registered in your configuration.
You can confirm that your app.json or app.config.js includes:

{
  "expo": {
    "plugins": ["rns-statusbar"]
  }
}

Then rebuild your native project:

npx expo prebuild

For local production builds:

eas build --platform android --local

🧱 Bare React Native Setup

If using plain React Native (without Expo):

iOS Setup

1. Install the package
2. Navigate to iOS directory and install pods

   cd ios && pod install

3. Rebuild your project.

Android Setup

1. Install the package
2. Sync Gradle and rebuild your project.

🧩 Usage Example

import React, { useEffect } from 'react';
import {
  SafeArea,
  getStatusBarHeight,
  getStatusBarColor,
  setStatusBarColor,
  useTopPadding,
} from 'rns-statusbar';

export default function App() {
  const topPadding = useTopPadding();

  useEffect(() => {
    setStatusBarColor('#20232a');     // Set background color
    getStatusBarHeight().then(console.log); // Log status bar height
    getStatusBarColor().then(console.log);  // Log current color
  }, []);

  return (
    <SafeArea style={{ backgroundColor: '#fff' }}>
      <Text style={{ marginTop: topPadding }}>Hello Status Bar!</Text>
    </SafeArea>
  );
}

🔧 API Reference

Functions

| Function | Type | Description | |-----------|------|-------------| | getStatusBarHeight() | Promise<number> | Returns status bar height in dp (defaults to 24). | | getStatusBarColor() | Promise<string> | Returns current status bar color (hex string). | | setStatusBarColor(color: string) | Promise<void> | Updates status bar background color. | | getTopPadding() | Promise<number> | Cached getter for status bar height. | | useTopPadding() | () => number | React hook returning the top padding. |

Component: SafeArea

Cross-platform container ensuring UI content is rendered safely beneath the status bar.
When used, it automatically handles keyboard visibility and eliminates the need for KeyboardAvoidingView.

<SafeArea style={{ backgroundColor: '#fff' }}>
  {children}
</SafeArea>

| Prop | Type | Description | |------|------|-------------| | style | ViewStyle | StyleProp<ViewStyle> | Custom container style. | | children | React.ReactNode | Nested content. |

🧾 TypeScript Support

Type definitions (index.d.ts) are included by default, ensuring full IDE support:

import { getStatusBarHeight, SafeArea, getStatusBarHeight, getStatusBarColor, setStatusBarColor, useTopPadding } from 'rns-statusbar';

🧑‍💻 Development & Local Testing

To test your local changes in another app:

# from your test app folder
yarn add file:../rns-statusbar
npx pod-install ios

📄 License

MIT License © 2025 — Raiidr

💬 Contributing

Contributions are welcome!
If you encounter a bug or want to suggest a feature, open an issue or submit a pull request on GitHub.