Skip to main content

AI Prompt

Add light and dark mode to my app using CSS prefers-color-scheme and the Despia runtime safe area variables.
In the Despia editor, before writing any code:
  • Under Status Bar settings, enable Fullscreen Mode
  • Disable Auto-Inject Safe Area so you can manage padding yourself in CSS
  • Set the Light Mode status bar text color to Black and the Dark Mode status bar text color to White in the editor. These are managed natively and must be configured here rather than in code
In CSS:
  • Define light and dark color tokens in :root using CSS custom properties
  • Override them inside @media (prefers-color-scheme: dark). Do not use JavaScript state or a custom toggle
  • Set color-scheme: light in :root and color-scheme: dark inside the media query. This tells the native container to render the status bar text as black in light mode and white in dark mode automatically
  • Fullscreen mode removes the status bar background entirely. Use padding-top: var(--safe-area-top) on your header to fill that space with your own background color via CSS. Apply padding-bottom: var(--safe-area-bottom) to your footer the same way. These variables are injected by the Despia runtime
Always disable Auto-Inject Safe Area in the Despia editor when using fullscreen mode. Leaving it enabled will result in double padding and broken layouts.
How it works: Enabling fullscreen mode in the Despia editor removes the status bar background entirely, giving you full control over that area in CSS. Your header’s background color extends up behind the status bar, and padding-top: var(--safe-area-top) ensures your content sits below it. The CSS color-scheme property signals to the native container which status bar text style to use, with no SDK call required. The prefers-color-scheme media query handles all visual theming automatically based on the user’s OS setting. The Despia runtime injects --safe-area-top and --safe-area-bottom CSS variables before your app starts, so they are available synchronously with no loading state.

​
Despia Editor Setup

Before writing any CSS, configure the following in the Despia dashboard under Status Bar settings:
SettingValueWhy
Fullscreen ModeEnabledRemoves the status bar background so you can manage that area yourself in CSS using the safe area insets
Auto-Inject Safe AreaDisabledLets you apply --safe-area-top and --safe-area-bottom yourself in CSS
Light Mode Status Bar Text ColorBlackEnsures readable dark text over your light background
Dark Mode Status Bar Text ColorWhiteEnsures readable light text over your dark background

​
Usage

​
CSS Color Tokens

Define your light and dark color tokens in :root and override them for dark mode. The color-scheme property controls the native status bar text color automatically. 
/* Light mode (default) */
:root {
  --bg: #ffffff;
  --text: #1e293b;
  --surface: #f1f5f9;
  --border: #e2e8f0;
  color-scheme: light;
}

/* Dark mode (activated automatically when the OS is in dark mode) */
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f172a;
    --text: #f8fafc;
    --surface: #1e293b;
    --border: #334155;
    color-scheme: dark;
  }
}

body {
  background-color: var(--bg);
  color: var(--text);
  margin: 0;
}

​
Safe Area Insets

With fullscreen mode enabled and Auto-Inject Safe Area disabled, the status bar background is gone and you own that space. Use --safe-area-top on your header so its background color fills the status bar area, and --safe-area-bottom on your footer to clear the home indicator: 
/* Header, sits directly below the status bar */
.header {
  padding-top: var(--safe-area-top);
  padding-left: 1rem;
  padding-right: 1rem;
  padding-bottom: 1rem;
  background-color: var(--surface);
  border-bottom: 1px solid var(--border);
}

/* Footer, sits directly above the home indicator */
.footer {
  padding-bottom: var(--safe-area-bottom);
  padding-top: 1rem;
  background-color: var(--surface);
  border-top: 1px solid var(--border);
}

​
Full Example

A complete CSS setup combining theming and safe area handling: 
:root {
  --bg: #ffffff;
  --text: #1e293b;
  --surface: #f1f5f9;
  --border: #e2e8f0;
  color-scheme: light;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f172a;
    --text: #f8fafc;
    --surface: #1e293b;
    --border: #334155;
    color-scheme: dark;
  }
}

body {
  background-color: var(--bg);
  color: var(--text);
  margin: 0;
}

.header {
  padding-top: var(--safe-area-top);
  padding-left: 1rem;
  padding-right: 1rem;
  padding-bottom: 1rem;
  background-color: var(--surface);
  border-bottom: 1px solid var(--border);
}

.footer {
  padding-bottom: var(--safe-area-bottom);
  padding-top: 1rem;
  background-color: var(--surface);
  border-top: 1px solid var(--border);
}

​
Optional: statusbartextcolor:// SDK Override

In most cases color-scheme handles status bar text color automatically and no SDK call is needed. The correct default should be configured in the Despia editor under Status Bar settings rather than set in code. If you have a specific runtime override case, for example navigating to a screen with a hardcoded background that does not follow your CSS tokens, the SDK command is available: 
import despia from 'despia-native';

despia('statusbartextcolor://black'); // Dark text, for light backgrounds
despia('statusbartextcolor://white'); // Light text, for dark backgrounds
Only use this as a last resort. Set the correct default in the Despia editor and let color-scheme handle the rest via CSS. Do not use this command to implement dark mode logic. That belongs in CSS.

​
Resources

  • NPM Package
  • View full NPM documentation for additional configuration options
For additional support or questions, please contact our support team at support@despia.com