To make WebView dark mode follow the phone, give your app a theme that turns dark at night, because WebView takes prefers-color-scheme from the app theme. Then add <meta name="color-scheme" content="dark light"> to pages you control. For sites without a dark design, allow algorithmic darkening with setAlgorithmicDarkeningAllowed().
Why WebView dark mode ignores the phone setting
WebView reads the app theme, so a light-only app shows light pages even when the phone is dark. Android’s WebView dark theme guide puts it plainly: “WebView always sets prefers-color-scheme according to isLightTheme.”
If isLightTheme is true or not set at all, pages see light. So you test on a dark phone, your CSS has a perfect @media (prefers-color-scheme: dark) block, and nothing changes.
React Native apps hit it too. A react-native-webview feature request describes the media query returning false inside an Android WebView with system dark mode on.
Three layers that decide what the page shows
WebView dark mode depends on three separate switches, and each one fixes a different symptom:
- The app theme. It sets the value of
prefers-color-schemethat the page sees. - The page’s own markup. The color-scheme meta tag tells WebView the page supports dark styles.
- Algorithmic darkening. WebView recolors pages that have no dark styles at all.
Since Android 10, apps can switch between light and dark themes with the system, per the same guide. Get the first layer wrong and the other two never matter.
Step 1: Give the app a theme that turns dark at night
The app theme is the switch WebView listens to, so it must report dark when the phone is dark. You need a night variant where isLightTheme resolves to false, usually through a values-night theme folder or a DayNight parent theme.
Check it before you touch web code. Open the page in Chrome DevTools over USB (see how to debug a WebView with DevTools) and run this in the console:
matchMedia('(prefers-color-scheme: dark)').matches
With the phone in dark mode you want true. A false means the theme is still light, and no CSS change will help.
Step 2: Add the color-scheme meta tag to your pages
The color-scheme meta tag tells WebView that a page has its own dark design. Android’s guide says the default mode “requires the meta tag to honor the web page’s prefers-color-scheme media queries,” and recommends this line in the <head>:
<meta name="color-scheme" content="dark light">
The MDN reference for color-scheme explains the order: dark light means the page prefers dark but also supports light. Don’t use only dark. MDN calls it invalid, since forcing dark on an incompatible page can leave it unreadable.
The color-scheme article on web.dev notes that the tag also changes form controls, scroll bars and system colors. And it lets the browser paint the dark background before your CSS arrives, which kills the white flash on load.
Step 3: Allow algorithmic darkening for pages without dark styles
Algorithmic darkening lets WebView recolor a page that has no dark theme of its own. Android’s guide says it applies when the content doesn’t use prefers-color-scheme and its author hasn’t disabled darkening.
For apps targeting Android 13 or higher, use the Jetpack Webkit method:
if (WebViewFeature.isFeatureSupported(WebViewFeature.ALGORITHMIC_DARKENING)) {
WebSettingsCompat.setAlgorithmicDarkeningAllowed(webView.settings, true)
}
The WebSettingsCompat reference says darkening is disallowed by default, so nothing happens until you call this. Skip the feature check and the method throws on devices whose WebView doesn’t support it. The current stable library is androidx.webkit:webkit:1.18.0, per the webkit release notes.
Which dark mode API to use for your target SDK
Your targetSdkVersion decides which API does anything at all. The old force-dark calls are deprecated and, per the AndroidX reference, are a no-op once you target API 33 or higher.
| Your situation | What to use |
|---|---|
| Target API 33+, page has dark CSS | Dark app theme at night + color-scheme meta tag |
| Target API 33+, page has no dark CSS | Dark app theme + setAlgorithmicDarkeningAllowed(true) |
| Target Android 12 or lower | setForceDark with FORCE_DARK_ON / FORCE_DARK_OFF |
| Target Android 12 or lower, your own dark CSS | Add DARK_STRATEGY_WEB_THEME_DARKENING_ONLY |
For older targets, the guide’s sample reads the uiMode configuration and sets FORCE_DARK_ON for UI_MODE_NIGHT_YES, FORCE_DARK_OFF otherwise. Since new Play uploads must target a recent API level (see Google Play’s target API rule), most apps today belong in the first two rows.
Common mistakes with WebView dark mode
- Changing only CSS. If the theme is light,
prefers-color-scheme: darknever matches. - Keeping
setForceDarkafter raising the target. The call silently stops working at API 33. Switch tosetAlgorithmicDarkeningAllowed. - Darkening a page that already has a dark design. With user-agent darkening, the guide says your dark media query “evaluates to
false”, so WebView’s recoloring replaces your hand-made palette. - A white flash on launch. Without the meta tag, the background paints light before your CSS loads. A dark splash screen alone won’t hide it.
My take: if you own the site, write real dark CSS, add the meta tag, and leave algorithmic darkening off. Use it only for content you can’t edit. The guide itself frames force dark as a backward-compatibility tool for apps without their own dark theme. Its limitation is real: it can’t read your intent, so you lose control of contrast on logos and brand colors.
How the WebToAPK Free builder handles theme
The WebToAPK Free builder lets you pick a light or dark theme for the app, alongside the name, icon, colour and navigation, as shown on how it works. That covers the app frame. Your pages still need their own dark CSS and the color-scheme meta tag.
If a page shows blank or white after you change themes, check the usual load problems in the WebView white screen guide before blaming the theme.
FAQ
Why does prefers-color-scheme always say light in my WebView?
WebView reads the app theme, not the phone setting. If isLightTheme is true or not set, the page sees light. Give the app a dark theme variant for night mode and the media query starts matching dark.
Is setForceDark deprecated?
Yes. The AndroidX reference marks it deprecated and says it does nothing in apps that target API 33 or higher. Use setAlgorithmicDarkeningAllowed instead.
Do I need the color-scheme meta tag?
For pages you control, yes. Android’s guide says WebView’s default mode needs the meta tag before it honors a page’s prefers-color-scheme rules, and recommends content=“dark light”.
Can WebView darken a site that has no dark theme?
Yes, through algorithmic darkening. It is off by default, applies only to pages without their own dark styles, and needs the ALGORITHMIC_DARKENING feature check before you call it.