Customising Status and Navigation Bar Colors in TWAs

A critical step in making a Progressive Web App (PWA) feel like a native Android application is cohesive branding. Many developers convert their PWAs to Android using a Trusted Web Activity (TWA) but leave the system status bar (the top bar containing notifications and battery levels) and the system navigation bar (the bottom bar with back and home gestures) styled with default system colours. This breaks visual continuity.

By default, Android system bars may display in solid black, light grey, or transparent white, which can create a jarring visual boundary at the top and bottom of your web content. This guide explains how to configure and dynamically update status and navigation bar colours in a TWA.

The Role of the Web App Manifest

The primary source of truth for the initial layout colours of your TWA is your Web App Manifest (typically manifest.json). When PWAtoApp reads your manifest to generate your signed APK and AAB, it parses specific keys to configure the Android wrapper.

There are two key manifest properties that control these system colours:

• theme_color: This property defines the default colour of the Android status bar when the app launches and during active sessions.
• background_color: This property defines the background colour of the splash screen and the window background that loads before the web assets have fully rendered.

For example, a typical manifest configuration should look like this:

{
  "name": "My Application",
  "short_name": "App",
  "theme_color": "#1a0dab",
  "background_color": "#ffffff",
  "display": "standalone"
}

When compiled into a TWA, the Android operating system reads the theme_color value and applies it to the system status bar, ensuring that the top of the app matches your brand's primary colour immediately upon launch.

Handling Dynamic Status Bar Changes

While the Web App Manifest sets the initial global status bar colour, your application may have different pages with distinct colour schemes, such as a dark checkout page or a light profile dashboard. You can dynamically modify the status bar colour directly from your web application using HTML meta tags.

To change the status bar colour dynamically using JavaScript, you can locate or create the theme-color meta tag and update its content value:

function setSystemBarColor(hexColor) {
  let metaThemeColor = document.querySelector('meta[name="theme-color"]');
  if (!metaThemeColor) {
    metaThemeColor = document.createElement('meta');
    metaThemeColor.setAttribute('name', 'theme-color');
    document.head.appendChild(metaThemeColor);
  }
  metaThemeColor.setAttribute('content', hexColor);
}

Inside a TWA, the underlying Chrome-powered Custom Tab engine listens to changes in this specific meta tag and updates the Android status bar colour in real time, mirroring native Android platform APIs.

Configuring the Navigation Bar Colour

The navigation bar at the bottom of modern Android devices presents a unique challenge. Unlike the status bar, standard web browsers do not universally map the Web App Manifest theme_color to the bottom navigation bar. Historically, this bar remained default black or white to prevent accessibility issues with the system back and home icons.

However, when converting your PWA via a TWA, you can configure the navigation bar colour inside your build settings. PWAtoApp supports this customisation during the conversion process, allowing you to match the bottom bar to your app's background or primary theme. This creates an immersive experience, especially on devices with gesture navigation enabled.

Light and Dark Mode Considerations

To deliver a premium user experience, your status and navigation bar colours must adapt when the user switches between system-wide light and dark themes. If your app has a dark mode but your status bar remains bright white, the contrast is visual clutter.

You can handle dynamic theme switches by combining CSS media queries with your JavaScript theme-switching logic. When your web application detects dark mode, update the meta theme tag:

const darkModeMatcher = window.matchMedia('(prefers-color-scheme: dark)');
function handleThemeChange(e) {
  if (e.matches) {
    setSystemBarColor('#121212');
  } else {
    setSystemBarColor('#ffffff');
  }
}
darkModeMatcher.addEventListener('change', handleThemeChange);
handleThemeChange(darkModeMatcher);

System Bar Styling Mapping Reference

The following table displays how system UI elements are controlled by web properties and TWA wrapper configurations:

Validating Your Custom Colors

To verify that your colours are configured correctly, test the compiled APK on multiple physical devices with different Android versions. Be sure to check both gesture navigation mode and the traditional three-button navigation bar layout. If the contrast between your custom status bar colour and the system status icons (battery, Wi-Fi) is poor, the Android system should automatically invert the icon colours to maintain readability. Ensure your selected brand hex code permits legible status icons.