Skip to main content

AI Prompt

Add dynamic status bar text color control to your application using the Despia SDK from: https://www.npmjs.com/package/despia-native\\
First, install the package:
npm install despia-native
Then import it:
import despia from 'despia-native';
Control status bar text color using:
  • despia('statusbartextcolor://black') for black text (use on light backgrounds)
  • despia('statusbartextcolor://white') for white text (use on dark backgrounds)
For the best experience:
  1. Go to Despia settings and enable fullscreen mode to disable the status bar background color
  2. Use var(--safe-area-top) CSS variable to accommodate the status bar space
  3. Detect system dark mode preference using window.matchMedia('(prefers-color-scheme: dark)')
  4. Dynamically update status bar text color based on your app’s current theme
This feature requires the despia-native npm package. Follow the installation instructions closely and do not modify the implementation.
How it works: The Despia SDK provides native bridge functionality to control the iOS/Android status bar text color dynamically through the statusbartextcolor://{white||black} command. When combined with fullscreen mode in Despia settings, you can create fully immersive experiences where your app controls the entire screen, including custom animations, transitions, and full-bleed imagery, with only the status bar text visible on top, styled to match your design.

​
Installation

npm install despia-native

import despia from 'despia-native';

​
Usage

​
1. Basic Status Bar Text Color Control

import despia from 'despia-native';

// Set status bar text to black (for light backgrounds)
despia('statusbartextcolor://black');

// Set status bar text to white (for dark backgrounds)
despia('statusbartextcolor://white');

​
2. Dark Mode Detection and Auto-Switching

import despia from 'despia-native';

// Check current system preference
const isDarkMode = window.matchMedia && 
  window.matchMedia('(prefers-color-scheme: dark)').matches;

// Set initial status bar color based on system preference
despia(isDarkMode ? 'statusbartextcolor://white' : 'statusbartextcolor://black');

// Listen for system theme changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
  despia(event.matches ? 'statusbartextcolor://white' : 'statusbartextcolor://black');
});

​
3. Theme-Aware Component Example

import { useEffect, useState } from 'react';
import despia from 'despia-native';

function App() {
  const [isDark, setIsDark] = useState(
    window.matchMedia('(prefers-color-scheme: dark)').matches
  );

  useEffect(() => {
    // Update status bar text color when theme changes
    despia(isDark ? 'statusbartextcolor://white' : 'statusbartextcolor://black');
  }, [isDark]);

  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleChange = (e: MediaQueryListEvent) => setIsDark(e.matches);
    
    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);

  return (
    <div className="app-root">
      <div 
        className="safe-area-top"
        style={{ height: 'var(--safe-area-top)' }}
      />
      
      <header className="app-header">
        <h1>Theme-Aware App</h1>
      </header>
      
      <main 
        className={isDark ? 'bg-gray-900 text-white' : 'bg-white text-gray-900'}
        style={{ flex: 1, padding: '1rem' }}
      >
        Your content here
      </main>
      
      <div 
        className="safe-area-bottom"
        style={{ height: 'var(--safe-area-bottom)' }}
      />
    </div>
  );
}

export default App;

​
Safe Area Integration

When controlling the status bar text color with fullscreen mode enabled, always accommodate the safe area space using CSS variables. The Despia native runtime automatically provides var(--safe-area-top) and var(--safe-area-bottom) CSS variables. 
.safe-area-top {
  flex-shrink: 0;
  height: var(--safe-area-top, env(safe-area-inset-top, 0));
}

.safe-area-bottom {
  flex-shrink: 0;
  height: var(--safe-area-bottom, env(safe-area-inset-bottom, 0));
}

// Top Safe Area Spacer
<div style={{ height: 'var(--safe-area-top)' }} />

// Your app content here

// Bottom Safe Area Spacer
<div style={{ height: 'var(--safe-area-bottom)' }} />

​
Resources

  • NPM Package: despia-native
  • CSS Variables: var(--safe-area-top) and var(--safe-area-bottom) automatically provided by Despia runtime
For additional support or questions about status bar implementation, please contact our support team at support@despia.com