Sync Android System Dark Mode with a Trusted Web Activity

When a user opens an application, they expect a cohesive visual transition. If their Android device is set to dark mode, a sudden bright white splash screen or a lingering light-coloured status bar before the web app loads creates a jarring user experience. Because a Trusted Web Activity is a hybrid architecture comprising a native Android app shell and a web application powered by Chrome, achieving a seamless dark mode transition requires synchronising both environments.

Understanding the Dual Architecture Challenge

In a Trusted Web Activity, the visual experience is split into two distinct layers. The first layer is the native Android app wrapper, which manages the launch process, splash screen, status bar, and navigation bar. The second layer is the web application rendering within the custom tab. If these two layers are not aligned, users will notice visual mismatches during app startup or when switching system themes.

Chrome automatically passes the system theme preference down to the web content. This allows your web app to read the user preference via media queries. However, the native Android wrapper must be explicitly configured to adapt its background, splash screen, and system navigation elements dynamically to avoid visual conflicts.

Configuring the Web Application with CSS

The primary mechanism for rendering dark themes on the web is the prefers-color-scheme CSS media query. Modern rendering engines within Chrome read the Android system settings and apply the matching styles automatically. To support this on the web side, your CSS stylesheet should declare theme variables or styles targeted to this query.

@media (prefers-color-scheme: dark) { :root { --background-color: #121212; --text-color: #ffffff; } }

Using standard CSS variables ensures that when the Android system toggles between light and dark themes, the web viewport adapts instantaneously without needing to reload the application. You can test this transition in Chrome DevTools by simulating the prefers-color-scheme CSS media feature.

Synchronising the Native Shell and Status Bars

While the web content updates automatically, the native status bar and navigation bar require configuration within the Android manifest and style resources. The native wrapper needs to utilize a day-night theme that references system configuration attributes.

By setting up your Android theme resources with DayNight variants, the native wrapper automatically changes the colour of the status bar text and icon indicators. On dark backgrounds, Android displays white icons, whereas on light backgrounds, it displays dark icons. This prevents status bar indicators from becoming invisible against the application background.

Comparing Dark Mode Implementations

Handling Dynamic Theme Switches in JavaScript

In some scenarios, you may want to execute specific JavaScript logic when the user toggles the Android system dark mode while your app is running. You can register an event listener on the media query using JavaScript. This allows the web app to synchronise any internal settings, save user preferences, or notify third-party embeds of the theme change.

const darkModeQuery = window.matchMedia('(prefers-color-scheme: dark)'); function handleThemeChange(e) { if (e.matches) { console.log('Switching web context to dark mode'); } else { console.log('Switching web context to light mode'); } } darkModeQuery.addEventListener('change', handleThemeChange);

This programmatic listener ensures that your single-page application remains responsive to real-time system settings without forcing a page refresh, keeping the state of the user session completely intact.

Optimising the Android Splash Screen

The final step in achieving dark mode harmony is configuring the splash screen. Since Android 12, the splash screen is controlled by the SplashScreen API, which requires specific resources for light and dark themes. The native configuration must point to a drawable icon and a background colour resource that resolve differently depending on the system theme configuration.

By defining your theme attributes in both the values and values-night resource directories of the Android project, the launcher can pull the correct background colour for the splash screen immediately, eliminating the common issue of white flashes during cold app launches on dark-mode-configured devices.