`window.statusbar.setBackgroundColor`: color with alpha results in black on older web view versions

[GitToTheHub]

Bug Report

Problem

Setting a status bar background color with an alpha value like #FFFF0000 by window.statusbar.setBackgroundColor on older web view versions like they are present on an Android 7 or 8 emulator, becuase they can't be update there, because no Google Play is available, it will result in a black color. E.g. for setting status bar to red:

window.statusbar.setBackgroundColor('#FFFF0000');

The following JavaScript code in cordova-js-src/plugin-android-statusbar.js will create the problem:

cordova-android/cordova-js-src/plugin/android/statusbar.js

Lines 60 to 61 in a63c1e1

	statusBarScript.style.color = value;
	var rgbStr = window.getComputedStyle(statusBarScript).getPropertyValue('color');

The value is assigned to style.color, then read back via computed style. If parsing fails or degrades on old WebView, computed color falls back to black, e.g. rgb (0, 0, 0).

Alpha 255 will be prepended after and producing [255,0,0,0]:

cordova-android/cordova-js-src/plugin/android/statusbar.js

Lines 69 to 71 in a63c1e1

	} else if (rgbVals.length === 3) {
	rgbVals = [255].concat(rgbVals);
	}

I debugged it in the Chrome dev tools on an Android 8.1 emulator, and it can be seen, that the value #FFFF0000 is computed to rgb (0, 0, 0):

This does not happen on an Android 9 emulator, where the WebView can be updated.

On Android the string could be just forwarded to the native side of the plugin, like it is done, when the color is set by preference in config.xml:

<preference name="StatusBarBackgroundColor" value="#FFFF0000" />

On iOS, that preference is not read directly at runtime from config.xml. It is transformed during prepare, then loaded by storyboard as a named color. So the behaviour is different there.

On iOS exists also a problem with Alpha when setting by window.statusbar.setBackgroundColor but this is on the native side: apache/cordova-ios#1659

Interestingly Visual Studio also don't uses the alpha channel and reads a color string #AAFFFFFF like #AAFFFF like it is currently on iOS the case:

What is expected to happen?

The color should be set with alpha on older web view versions.

What does actually happen?

The color results in black on older web view versions.

Information

Command or Code

Environment, Platform, Device

Version information

Checklist

• I searched for existing GitHub issues
• I updated all Cordova tooling to most recent version
• I included all the necessary information above

[dpogue]

On Android the string could be just forwarded to the native side of the plugin, like it is done, when the color is set by preference in config.xml:

This is not true because it's valid to call setBackgroundColor with any valid CSS colour that the browser understands. All of these are allowed and equivalent:

• setBackgroundColor("red")
• setBackgroundColor("#ff0000")
• setBackgroundColor("rgb(255, 0, 0)")
• setBackgroundColor("hsl(0, 100%, 50%)")
• setBackgroundColor("#ff0000ff")
• setBackgroundColor("#f00")
• setBackgroundColor("oklab(0.5 0.4 0.4)")

[GitToTheHub]

This is not true because it's valid to call setBackgroundColor with any valid CSS colour that the browser understands. All of these are allowed and equivalent:

• setBackgroundColor("red")
• setBackgroundColor("#ff0000")
• setBackgroundColor("rgb(255, 0, 0)")
• setBackgroundColor("hsl(0, 100%, 50%)")
• setBackgroundColor("#ff0000ff")
• setBackgroundColor("#f00")
• setBackgroundColor("oklab(0.5 0.4 0.4)")

I don't understand why this is the case for a custom created method on the statusbar API. Can you explain this maybe?

[dpogue]

Because the way this is supposed to be handled is using the meta theme-color tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/theme-color
The custom JS API we added on iOS is only intended for cases where the theme-color option doesn't work, but it was intended to support all the same values.

Unfortunately, while iOS WKWebView gives us a themeColor property as of iOS 15.4, the Android WebView does not give us any access to the page's declared theme colour (yet). I've got PRs submitted to the Android WebView to support it, but Google is being slow about reviewing them (see https://issues.chromium.org/issues/506193601)

So we're stuck with this custom API that was never supposed to exist as the only option on Android for the moment. Luckily, the browser is doing all the work to handle parsing of the CSS colours, and the Java side just needs to deal with 3 or 4 component integers (which it should already be doing).

[GitToTheHub]

Thank you for explaining the background. I didn't know about that background.

The custom JS API we added on iOS is only intended for cases where the theme-color option doesn't work, but it was intended to support all the same values.

But why the custom JS API was added, when support for the preference StatusBarBackgroundColor of config.xml was added also?

Reagarding you issue on Chromium, you write:

so app UI such as ActionBars can be tinted to match the website theme.

So the equivalent of theme-color would be the preference BackgroundColor of config.xml? But I see BackgroundColor also tints the splash screen. So theme-color is a middle between StatusBarBackgroundColor and BackgroundColor?

If theoretically meta theme-color tag would be supported by iOS and Android, would the custom JS API still be needed and could the preference StatusBarBackgroundColor of config.xml than be dropped?

Unfortunately, while iOS WKWebView gives us a themeColor property as of iOS 15.4, the Android WebView does not give us any access to the page's declared theme colour (yet).

So did I understand correctly, that the custom JS API is added to iOS because iOS 15.4 gives access to the themeColor property, or what do you mean before with is only intended for cases where the theme-color option doesn't work?

[erisu]

StatusBarBackgroundColor is a preference intended to set the status bar background color at startup. Configuration preferences are not intended to be changed throughout the app lifecycle. For simple apps setting this config would apply across all pages.

The purpose of the JavaScript API is not new. While it may have a different method name than the original implementation and added to the platform core, this API has existed in the StatusBar plugin since v1.0.0.

It is intended for specific use cases. For example, an app may have multiple views with different background colors, and the developer may want the status bar to match the background color of the current page. This API allows the status bar color to be changed dynamically.

Ideally, I would encourage apps to migrate to Edge-to-Edge and avoid using a status bar altogether. However, the API and behavior that support dynamically changing the status bar background color are not new. It was added to core to maintain previous behavior for apps that don't switch to Edge-to-Edge.

[GitToTheHub]

Thanks for explanation. I want to gather all informations about it, so I can make a proper documentation. Ok, so both is needed, the config.xml and JS API to be backward compatible. I was also thinking, that the goal should be to use edge-to-edge for Android and for iOS vieport-fit=cover. So the user handles the status bar part itself by HTML. Is this correct?

[johuether]

Hi! I'm also affected by this and think it's a real bug/problem. I've narrowed it down a bit further on the native side.

My setup: an app that targets Android 17 (API 36) and uses edge-to-edge mode. Looks good on newer Android versions, but on older devices the status bar is solid black and can't be made transparent through the plugin (window.statusbar.setBackgroundColor(...) with a transparent/alpha color).

What I found

Even when the correct ARGB value actually reaches the native side, SystemBarPlugin.updateStatusBar() unconditionally paints the color onto the in-app statusBar overlay:

View statusBar = getStatusBarView(webView);
if (statusBar != null) {
    statusBar.setBackgroundColor(bgColor);
}

That overlay approach is what's needed on API 35+ (Android 15+, VANILLA_ICE_CREAM), where the platform ignores window.setStatusBarColor(...) and forces the bar transparent. On older devices, though, setStatusBarColor(...) works at the window level - but only if the window is allowed to draw its own system bar background. Without that, a transparent request just gets ignored and the bar falls back to the default opaque/black decoration, which is exactly the black bar I'm seeing.

Suggested fix

Branch on the build version: on API 35+ keep the overlay behavior, on older devices set the color directly at the window level. Picking one path or the other also avoids double-blending translucent colors.

    @SuppressWarnings("deprecation")
    private void updateStatusBar(int bgColor) {
        Window window = cordova.getActivity().getWindow();

        // API 35+ ignores window.setStatusBarColor (the platform forces the bar
        // transparent), so paint via the in-app overlay there. On older devices
        // color the system bar directly at the window level. Using one or the
        // other (not both) also avoids double-blending translucent colors.
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            View statusBar = getStatusBarView(webView);
            if (statusBar != null) {
                statusBar.setBackgroundColor(bgColor);
            }
        } else {
            window.setStatusBarColor(bgColor);
        }

        // Automatically set the font and icon color of the system bars based on background color.
        boolean isStatusBarBackgroundColorLight;
        if (bgColor == Color.TRANSPARENT) {
            isStatusBarBackgroundColorLight = isColorLight(getUiModeColor());
        } else {
            isStatusBarBackgroundColorLight = isColorLight(bgColor);
        }
        WindowInsetsControllerCompat controllerCompat = WindowCompat.getInsetsController(window, window.getDecorView());
        controllerCompat.setAppearanceLightStatusBars(isStatusBarBackgroundColorLight);
    }

With this the status bar becomes properly transparent on older devices in edge-to-edge mode, and API 35+ keeps the current overlay behavior. Happy to turn it into a PR if there's interest.

[ollm]

I think the changes introduced in #1971, available in cordova-android 15.1.0, should resolve this issue.

More info: #1967 (comment)

[GitToTheHub]

Thanks everyone for the investigation and testing. I am closing this issue as not actionable on Cordova side.

The status bar JS API accepts CSS color values correctly since PR #1955, which was released by cordova-android 15.1.0. The observed mismatch for 8-digit hex colors is a WebView compatibility behavior tracked in Chromium issue 40472321, not a Cordova-native color conversion bug. A fix would be to use the rgba() pattern like window.statusbar.setBackgroundColor('rgba(255, 0, 0, 1)'); which would work as an opaque red.

The issue about the 8-digit-hex colors is influenced by both WebView engine version and app targetSdkVersion. New enough WebView/Chromium support >= 62+ is required for CSS 8-digit hex in general. Android WebView also applies legacy compatibility behavior for apps targeting API 27 (Android 8.1) or lower. Standard CSS behavior is used for apps targeting API 28 (Android 9) or higher.

[johuether]

Thanks for the wrap-up and the explanation! Just to clarify: I'm already on cordova-android 15.1.0 (so PR #1971 is included), and the rgba() workaround for the 8-digit-hex parsing works fine for me too - that part I can work around.

The problem I was pointing at is a separate one though, and it still happens even when the color reaches the native side correctly - e.g. window.statusbar.setBackgroundColor('rgba(0, 0, 0, 0)') or any ARGB with the alpha in the right place. On older devices I can't get the status bar to become transparent in edge-to-edge mode - it stays solid black.

[GitToTheHub]

On older devices I can't get the status bar to become transparent in edge-to-edge mode - it stays solid black.

If you use <preference name="AndroidEdgeToEdge" value="true" /> in config.xml and don't use the plugin cordova-plugin-statusbar and use cordova-android 15.1.0 the status bar should be always transparent. Here a screenshot on an Android 7.1.1 Emulator:

In edge-to-edge mode the status bar is always transparent. The background color cannot be set only the dark/light appearance.

[GitToTheHub]

But thanks to your comment, I noticed that StatusBarOverlaysWebView is not supported in cordova-android 15, when the app is not in edge-to-edge mode. This fixed I in #1991.

[ollm]

It might be because of what I mentioned in #1983.

Note

I'm not sure if this is intentional, but I wanted to mention it. If #00000000 is passed to setBackgroundColor, the following code treats it as fully transparent, so the navigation bar color is not changed to the expected one (White icons). For now, I'm using #01010100 as a workaround.

cordova-android/framework/src/org/apache/cordova/SystemBarPlugin.java

Lines 189 to 193 in ed4e629

	if(bgColor == Color.TRANSPARENT) {
	isBackgroundColorLight = isColorLight(getUiModeColor());
	} else {
	isBackgroundColorLight = isColorLight(bgColor);
	}

[GitToTheHub]

Since you cannot change the background color of the status bar when AndroidEdgeToEdge is true but influence the appearance of it, you can just set the background color without an alpha value, like #000000. This would result in white icons. You can also set black for getting white icons.