Statusbar

The Despia StatusBar Colors SDK enables your application to customize the status bar appearance on mobile devices. This feature allows you to match the status bar background and text colors with your app's design, supporting both light and dark mode for a cohesive user experience.

Quick Start

1. Set Status Bar Background Color

Set the background color of the status bar using RGB values.

Copywindow.despia = `statusbarcolor://255, 255, 255`

2. Set Status Bar Text Color

Set the text color of the status bar to either black or white.

Copywindow.despia = `statusbartextcolor://black`

3. Implement Dark Mode Support

Adjust colors based on the device's theme for proper light/dark mode support.

Copy// Check if device is in dark mode
const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;

// Set appropriate colors based on mode
if (isDarkMode) {
  window.despia = `statusbarcolor://33, 33, 33`;
  window.despia = `statusbartextcolor://white`;
} else {
  window.despia = `statusbarcolor://255, 255, 255`;
  window.despia = `statusbartextcolor://black`;
}

How It Works

The StatusBar Colors SDK interfaces directly with native mobile operating systems to customize the appearance of the status bar. When you call the SDK using the provided syntax:

• Background Color: The statusbarcolor:// command sets the RGB background color of the status bar

• Text Color: The statusbartextcolor:// command sets the color of text and icons in the status bar

• Native Implementation: Changes are applied immediately at the OS level without requiring a page refresh

Implementation Examples

Here's how you can implement the StatusBar Colors SDK in your project:

Copy// Basic implementation
window.despia = `statusbarcolor://255, 255, 255`;
window.despia = `statusbartextcolor://black`;

// EXAMPLES FOR NO-CODE/LOW-CODE TOOLS
            
// ---------- WEWEB ----------     
// No callback is needed, so you can simply execute this code in a code block
// No need to update WeWeb variables

// ---------- WIZED ---------- 
// No callback required - just run this code in a custom action
window.despia = `statusbarcolor://255, 255, 255`;
window.despia = `statusbartextcolor://black`;
            
// ---------- NORDCRAFT / TODDLE ---------- 
// Clone the package from here: https://toddle.dev/projects/despia_package/branches/main
// Or add this simple implementation without callbacks as a custom action
window.despia = `statusbarcolor://255, 255, 255`;
window.despia = `statusbartextcolor://black`;

Data Structure

The StatusBar Colors SDK uses simple string commands with no returned data structure.

Copy// Background color command structure
`statusbarcolor://{red}, {green}, {blue}`

// Text color command structure
`statusbartextcolor://{color}`  // where color is either "black" or "white"

Best Practices

Color Selection

• Choose background colors that match your app's header or primary color

• Ensure sufficient contrast between background and text colors

• Test both light and dark mode configurations

Implementation

• Set status bar colors early in your app lifecycle

• Update colors when theme changes occur

• Implement theme detection for automatic light/dark mode switching

User Experience

• Avoid frequently changing status bar colors

• Consider platform differences between iOS and Android

• Match status bar appearance with overall app design

Complete Implementation Example

Here's a complete example implementing StatusBar Colors with theme support:

Copy// StatusBar Colors Implementation with Theme Support

// Function to update status bar based on theme
function updateStatusBarColors(isDark) {
  if (isDark) {
    // Dark mode colors
    window.despia = `statusbarcolor://33, 33, 33`;
    window.despia = `statusbartextcolor://white`;
  } else {
    // Light mode colors
    window.despia = `statusbarcolor://255, 255, 255`;
    window.despia = `statusbartextcolor://black`;
  }
}

// Check initial theme
const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
updateStatusBarColors(isDarkMode);

// Listen for theme changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
  updateStatusBarColors(event.matches);
});

Troubleshooting

Common Issues

Colors Not Applying

• Ensure the syntax is correct with proper RGB values (0-255)

• Verify the device supports status bar customization

• Check that the app has the proper permissions

Text Color Incorrect

• Verify you're using exactly "black" or "white" as the only valid options

• Ensure sufficient contrast with the background color

• Test on both iOS and Android as implementations may vary slightly

Theme Support Issues

• Verify that theme detection is working correctly

• Test theme changes in real devices, not just emulators

• Implement a manual override option for users