Option to completely disable the built-in window.statusbar plugin

[ollm]

Feature Request

Motivation Behind Feature

I'm using my own status bar plugin because it provides additional functionality that is not available in the built-in implementation, such as proper edge-to-edge support and the ability to retrieve the status bar height.

Since the built-in status bar plugin was introduced in Cordova Android, I've been experiencing conflicts between the two implementations. For example, the status bar icon color changes unexpectedly a few moments after the app starts, most likely when the built-in plugin updates the status bar.

The simplest solution would be to provide an option to completely disable the built-in plugin so developers can use their own implementation without interference.

Feature Description

Add a configuration option that completely disables the built-in window.statusbar plugin, preventing it from initializing or modifying the status bar.

This would allow custom plugins, such as my own implementation, to work without conflicts:
https://github.com/ollm/cordova-plugin-statusbar/tree/feature/addGetStatusBarHeightMethod

Alternatives or Workarounds

The current workaround is to remain on Cordova Android 14.0.1, where the built-in status bar plugin is not present.

[breautek]

Notwithstanding the bug present 15.0.0 (you can test against github's master branch for the fix) -- using cordova-android@15 with AndroidEdge2Edge preference enabled is effectively what you're already asking I think.

While in this mode:

• The window.statusbar API is still present but it is a no-op.
• Cordova makes no status bar view -- there is simply the system bar.
• The webview is rendered full screen, and will overlay underneath system bars.
• Safe area insets can be used to pad or offset your content to clear system bars and other screen obstacles. It's my understanding this will require a fairly recent webview version installed on the device. Alternatively a plugin that reports the safe area insets sourced from the native views can be used, which is similar to what your status bar fork is already doing.

If you're still using cordova-plugin-statusbar -- the plugin will still initialize and control the status bar to some degree. The plugin still offers features that is not available in the "core" statusbar implementation.

Notwithstanding the bug present 15.0.0

on 15.0.0 there is a bug where the webview is not positioned properly resulting in a white bar appearing in the status bar area, which is fixed but pending release at the time of writing. So for testing purposes, it's worth to install the platform directly from github.

Can you let me know where the gaps are?

[ollm]

Thanks for the reply!

I tested the latest master branch, and the issue still persists (I have AndroidEdgeToEdge enabled).

I'd like to clarify that the problem is in the status bar icon colors (which can be either black or white). I've attached videos showing the issue.

cordova-android 14.0.1 (Without the issue, it stays white)

Grabacion.de.pantalla.desde.2026-07-07.18-28-21.webm

cordova-android 15.1.0 (With the issue, it turns black after a while)

Grabacion.de.pantalla.desde.2026-07-07.18-44-42.webm

Safe area insets can be used to pad or offset your content to clear system bars and other screen obstacles. It's my understanding this will require a fairly recent webview version installed on the device. Alternatively a plugin that reports the safe area insets sourced from the native views can be used, which is similar to what your status bar fork is already doing.

I think it's still a bit too early to rely solely on safe-area-inset-top, since it's only available starting with WebView 149, which was released just a couple of months ago. https://caniuse.com/mdn-css_types_env_safe-area-inset-top

I wanted to mention that I had to install it locally and modify the version, because when installing it from the repository, the 15.1.0-dev.0 version isn't compared correctly, causing some plugins to fail to install.

Installing "cordova-plugin-firebasex-core" for android
Plugin doesn't support this project's cordova-android version. cordova-android: 15.1.0.0, failed version requirement: >=14.0.0
Skipping 'cordova-plugin-firebasex-core' for android

[GitToTheHub]

Maybe we can add a workaround for --safe-area-inset-* beeing 0? The article https://medium.com/androiddevelopers/make-webviews-edge-to-edge-a6ef319adfac shows how to set --safe-area-inset-* css variables by JavaScript from the native code. This can be used if the safe-area-inset-* css environment variables are 0. Is this the only reason for using your custom plugin?

Also I see your fork depends on a fork which lies 39 commit behind which points to a 3.0.0-dev version of cordova-plugin-statusbar. The current released version is 4.0.0.

You can still use cordova-plugin-statusbar in cordova-android 15.x. If it is your custom one and depends on the released version 4.0.0 of cordova-plugin-statusbar, your custom plugin should work.

[breautek]

I think it's still a bit too early to rely solely on safe-area-inset-top, since it's only available starting with WebView 149, which was released just a couple of months ago. https://caniuse.com/mdn-css_types_env_safe-area-inset-top

I agree -- that's why I mention using a plugin to bridge that gap. At my workplace we use https://github.com/totalpaveinc/cordova-plugin-insets to do this, which does something pretty close to what your statusbar fork does.

I think on my apps the statusbar stays white -- but I don't have the statusbar plugin installed anymore either so perhaps that's why? I'll test and try to track down exactly what or how the status bar color gets decided.

Maybe we can add a workaround for --safe-area-inset-* beeing 0? The article https://medium.com/androiddevelopers/make-webviews-edge-to-edge-a6ef319adfac shows how to set --safe-area-inset-* css variables by JavaScript from the native code.

I would refrain adding in workarounds in the core framework especially when it's expected to be temporarily. Such workarounds should be in a plugin.

[GitToTheHub]

At my workplace we use https://github.com/totalpaveinc/cordova-plugin-insets to do this, which does something pretty close to what your statusbar fork does.

This is a nice solution too. Would it be ok to link to it from the Cordova docs?

I would refrain adding in workarounds in the core framework especially when it's expected to be temporarily. Such workarounds should be in a plugin.

So you mean this could be added to the status bar plugin?

[breautek]

So you mean this could be added to the status bar plugin?

No -- I mean we should avoid adding in hacks to workaround a problem in the Apache codebase which we would then have to maintain for an extended period of time. Sometimes it is necessary but in this particular case where the issue is resolved upstream already in the android webview -- just requires a modern webview version installed on the user device.

The real problem is with any workarounds implemented today will get obsolete in the near future -- and it will involve setting a custom CSS variable instead of using the proper env(safe-area-inset-*) variable. If we implement a workaround in the core framework, then apps will start depending on the custom variable instead and removing the workaround will become very difficult and become migration pain point. Therefore Apache shouldn't take responsibility on that front.

[breautek]

I'll test and try to track down exactly what or how the status bar color gets decided.

I think I traced down the logic here -- it starts at

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

Line 150 in cdbeb60

Integer rootViewBackgroundColor = getPreferenceBackgroundColor();

Basically it tries to determine the background color of the statusbar area and does a luminescence check to determine if it should use light or dark appearance...

In the case of E2E mode the background color is always 0 aka TRANSPARENT, in which case it uses:

/**
     * Determines the background color for status bar & root layer.
     * The color will come from the app's R.color.cdv_background_color.
     * If for some reason the resource is missing, it will try to fallback on the uiMode.
     * <p>
     * The uiMode as follows.
     *   If night mode: "#121318" (android.R.color.system_background_dark)
     *   If day mode: "#FAF8FF" (android.R.color.system_background_light)
     * If all fails, light mode will be returned.
     * </p>
     * The hex values are supplied instead of "android.R.color" for backwards compatibility.
     *
     * @return int color
     */
    @SuppressLint("DiscouragedApi")
    private int getUiModeColor() {
        boolean isNightMode = (resources.getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK) == Configuration.UI_MODE_NIGHT_YES;
        String fallbackColor = isNightMode ? "#121318" : "#FAF8FF";
        int colorResId = resources.getIdentifier("cdv_background_color", "color", context.getPackageName());
        return colorResId != 0
                ? ContextCompat.getColor(context, colorResId)
                : Color.parseColor(fallbackColor);
    }

Basically this tries to get the cdv_background_color resource which by default (and appears to be hard-coded) it uses #FAF8FF for day, and #121318 for night -- these same values are used as a fallback if the color resource is not in the app resources. So the color you get would depend on the system appearance settings (whether the OS is using a dark "night" theme or not).

I operate my device in dark theme so the statusbar stays white... But users operating in light theme will get a dark font status bar.

This is obviously not really ideal because regardless of the OS theme, it might not match what is actually rendered on the screen in E2E mode. So definite room for improvement here.

Using <edit-config> on the cdv_colors.xml resource to replace cdv_background_color might be a workaround...

There are 4 places that would need manipulation:

• values/cdv_themes.xml
• values-34/cdv_themes.xml
• values-night/cdv_themes.xml
• values-night-34/cdv_themes.xml

[ollm]

Maybe we can add a workaround for --safe-area-inset-* beeing 0? The article https://medium.com/androiddevelopers/make-webviews-edge-to-edge-a6ef319adfac shows how to set --safe-area-inset-* css variables by JavaScript from the native code. This can be used if the safe-area-inset-* css environment variables are 0. Is this the only reason for using your custom plugin?

This isn't a problem for me. After some time has passed, I'll probably switch completely to env(safe-area-inset-*) (Which I'm already using on iOS), although I'll continue using the custom plugin for the following features.

• StatusBar.overlaysWebView(true): I've always had the WebView fill the entire screen, with transparent/semi-transparent system bars on old Android versions that don't support edgeToEdge.
• StatusBar.styleLightContent(): Changes the status bar icons to white when the app is using the dark theme, or when the light theme has a header image.
• StatusBar.styleDefault(): Changes the status bar icons to black when the app is using the light theme.
• StatusBar.height(): Returns the height of the status bar, since env(safe-area-inset-*) didn't previously work on Android.

Out of all these, I do think StatusBar.styleLightContent() and StatusBar.styleDefault() should be implemented in the built-in plugin (On both iOS and Android), as they're often needed depending on the app's theme or design.

I've attached a video showing an example of the use of styleLightContent() and styleDefault() in my app.

Screen_recording_20260707_211218.webm

[ollm]

Using <edit-config> on the cdv_colors.xml resource to replace cdv_background_color might be a workaround...

There are 4 places that would need manipulation:

• values/cdv_themes.xml
• values-34/cdv_themes.xml
• values-night/cdv_themes.xml
• values-night-34/cdv_themes.xml

But wouldn't this only be configurable at build time? In my app, the theme (light/dark mode) can be controlled by the user in three different ways: Device, Enabled, Disabled.

[breautek]

But wouldn't this only be configurable at build time? In my app, the theme (light/dark mode) can be controlled by the user in three different ways: Device, Enabled, Disabled.

Correct -- you wouldn't have runtime control. Something I thought after I posted lol.

Out of all these, I do think StatusBar.styleLightContent() and StatusBar.styleDefault() should be implemented in the built-in plugin (On both iOS and Android), as they're often needed depending on the app's theme or design.

I think I can probably agree with this. I've been kind out of the development loop with Apache but it's my understanding that they tried to keep a very basic statusbar implementation the core -- while continue to support the cordova-plugin-statusbar for more advanced functionality. So this might be a case where the statusbar plugin would be recommended to be installed (or in your case your fork) to maintain access to .styleLightContent() and .styleDefault() APIs.

But that brings back to originally reported conflict I assume right? Where there is a conflict between the core system statusbar setting the status bar appearance overriding the statusbar plugin?

[ollm]

But that brings back to originally reported conflict I assume right? Where there is a conflict between the core system statusbar setting the status bar appearance overriding the statusbar plugin?

Yes, exactly. I'm not sure if it's the right approach, but I think the simplest solution would be to add a new option that prevents the built-in plugin from modifying the status bar.

[breautek]

Yes, exactly. I'm not sure if it's the right approach, but I think the simplest solution would be to add a new option that prevents the built-in plugin from modifying the status bar.

Yah maybe -- but I think that would have to be a conditional. I think the builtin implementation is fine if the app isn't relying on any external statusbar plugin. But if the statusbar plugin is used, then statusbar management should delegated to it. Just not sure if there any other negative repercussions that will cause.

In the meantime though, you can use this hook:

Hook Code

const FileSystem = require('fs');
const Path = require('path');

// The colour to force cdv_background_color to across all resource variants.
const TARGET_COLOR = '#000000';

// cordova-android generates cdv_colors.xml in several resource-qualifier
// directories. Each may define cdv_background_color with a different value
// (light / dark / Android 14+ dynamic), so we rewrite them all.
const VARIANT_DIRS = [
    'values',
    'values-night',
    'values-v34',
    'values-night-v34'
];

// Matches: <color name="cdv_background_color">ANYTHING</color>
// - handles single/double quotes and arbitrary inner whitespace
// - captures the opening tag so we can preserve its exact formatting
const COLOR_REGEX = /(<color\s+name=(?:"|')cdv_background_color(?:"|')\s*>)([\s\S]*?)(<\/color>)/g;

module.exports = function (context) {
    const projectRoot = (context && context.opts && context.opts.projectRoot) || process.cwd();
    const resRoot = Path.join(projectRoot, 'platforms', 'android', 'app', 'src', 'main', 'res');

    VARIANT_DIRS.forEach((dir) => {
        const file = Path.join(resRoot, dir, 'cdv_colors.xml');

        if (!FileSystem.existsSync(file)) {
            return;
        }

        const original = FileSystem.readFileSync(file, 'utf8');
        const updated = original.replace(COLOR_REGEX, `$1${TARGET_COLOR}$3`);

        if (updated !== original) {
            FileSystem.writeFileSync(file, updated, 'utf8');
            console.log(`[overrideCdvBackgroundColor] set cdv_background_color=${TARGET_COLOR} in ${Path.join('res', dir, 'cdv_colors.xml')}`);
        }
    });
};

and reference it in your config.xml:

<hook type="after_prepare" src="path/to/hook.js" />

The edit-config I guess doesn't do replacement of node text, just node attributes -- so it isn't actually usable to replace the color content. This allows the app to choose a status bar appearance based on the target color -- if it's a darker color it will produce a light appearance for constrast and vice versa.

Then you should be able to use the old statusbar plugin API to control the appearance style during runtime.

For a proper fix moving forward I'll probably have to talk to some people but hopefully the above could be a stopgap solution for the time being.

[dpogue]

A few thoughts here:

1. We should probably always determine the text colour based on the StatusBarBackgroundColor preference or the last (non-transparent) status bar background set via JS, even in E2E mode. That would at least provide a way to set the status bar colour (even if the status bar background isn't visible) to match the app and automatically determine the contrasting text colour.

2. On iOS, the built-in status bar implementation is entirely conditional on the CDVStatusBar class not existing in the app. I think on Android that ended up not being easy to do because the layout structure needed to change with E2E to support faking non-E2E on newer Android versions.

The goal from my perspective was always that the core platform would provide enough to show/hide a solid background behind the status bar based (ideally) on the viewport-fit meta directive in the HTML, and that the background of that solid bar would be determined (ideally) by a theme-color meta directive in the HTML. The window.statusbar.setBackgroundColor API was added to allow apps to force it in places where theme-color isn't supported (iOS <15.4, Android all versions currently), and window.statusbar.visible is supported to show or hide the status bar background temporarily.

[ollm]

The hook would only change the status bar icons from black to white, causing the issue to appear with the light theme instead.

Internally, when the app starts, I already set the status bar icons based on the theme selected by the user (light/dark). The problem is that the built-in status bar implementation applies its own change a few seconds later, overriding what I already set.

I've attached a new video showing the hook applied and the issue occurring with the light theme now.

Grabacion.de.pantalla.desde.2026-07-08.10-39-00.mp4

[GitToTheHub]

1. We should probably always determine the text colour based on the StatusBarBackgroundColor preference or the last (non-transparent) status bar background set via JS, even in E2E mode. That would at least provide a way to set the status bar colour (even if the status bar background isn't visible) to match the app and automatically determine the contrasting text colour.

I created PR #1971 which removes the canEdgeToEdge check in the execute method of the SystemBarPlugin. By this a user can dynamically change the dark/light appearance of the status bar by setting a light or dark status bar background. For e.g. calling window.statusbar.setBackgroundColor('white'); would set a white status bar background, which is not visible in edge-to-edge, and would lead to a dark appearance of the status bar setting dark text and icons. The opposite would be to call window.statusbar.setBackgroundColor('black'); which would lead to a light appearance of the status bar setting light text and icons.