cordova-plugin-splashscreen: a browser splash screen for Cordova apps

A launch screen that appears before the app has started

The plugin displays and hides a splash screen while your web application is launching, and its methods let you show and hide the splash screen manually. That is the whole scope, and the description in the README is accurate about it.

The interesting part is the timing. The README explains that your application cannot call navigator.splashscreen.show() until it has started and the deviceready event has fired, which would seem to defeat the purpose of a splash screen, since a splash screen is meant to be visible before the application has started. The resolution is that providing any parameters in config.xml automatically shows the splash screen immediately after the application is launched and before it has fully started and received the deviceready event. For that reason the README says it is unlikely you will need to call show() yourself.

So the plugin is really two things: a configuration-driven launch screen that appears automatically, and a pair of JavaScript methods for the case where you want to control it from code. The automatic path is the one that matters for most apps, and it is configured entirely from config.xml.

The audience is a Cordova developer whose app has a slow enough start to need something to look at, and who wants that behaviour declared in configuration rather than in application code. The plugin lives under the Apache Software Foundation, and the licence is Apache-2.0, with the LICENSE and NOTICE files at the repository root.

The version in the package metadata is 7.0.0-dev, and the repository has no GitHub releases, with a RELEASENOTES.md file at the root instead.

The supported platform list has narrowed to Browser

The README lists a single supported platform, Browser, and the package metadata agrees. The cordova block names the plugin id as cordova-plugin-splashscreen and the platforms array contains only browser. The keywords list cordova-browser alongside cordova, splashscreen and ecosystem:cordova, and the cordovaDependencies block in the metadata still records older Cordova versions against cordova-android, cordova-windows and cordova-ios.

That combination deserves a careful reading. The cordovaDependencies table maps Cordova versions to platform requirements, including entries for android at 3.6.0 and windows at 4.4.0, and constrains cordova-ios below 6.0.0 for Cordova versions below 6.0.0, with a Cordova 8.0.0 entry requiring cordova greater than 100. Those entries read like history preserved for older Cordova releases, while the platforms array describes what the current version of the plugin actually targets.

For an adopter this is the first question to answer: does the platform you build for appear in that array? The README's own supported platforms section answers it for the current state of the project, and it says Browser.

The repository layout shows what is left in the tree. There is a src directory for the plugin source, a www directory for the JavaScript interface, a tests directory, a types directory, and a plugin.xml file that Cordova uses to install the plugin. The primary language is listed as JavaScript, and the topic tags include cplusplus, csharp, java and objective-c, which are the native sides of a plugin that once had platform-specific implementations.

The tooling is minimal and appropriate for a plugin of this size. The test script is npm run lint, and lint runs eslint over the project using the @cordova/eslint-config package. There is also a licence_checker.yml file and a .rat-excludes file, both part of the Apache release process, and an .asf.yaml file for the foundation's own project metadata.

Installing the plugin and wiring the launch preferences

Installation is a Cordova plugin add, either from npm or straight from the repository:

    cordova plugin add cordova-plugin-splashscreen

    cordova plugin add https://github.com/apache/cordova-plugin-splashscreen.git

Configuration lives in the top-level config.xml file, not the one in the platforms directory, which the README is explicit about. The first example in the README sets a delay of ten seconds:

<preference name="SplashScreenDelay" value="10000" />

The value of the src attribute for the image is relative to the project root directory and not to the www directory, and you can name the source image file whatever you like because the internal name in the application is determined automatically by Cordova. The directory structure the README shows has a res directory with a screen subdirectory, sitting alongside the usual hooks, platforms, plugins and www directories, and the image goes there rather than into www/img.

The preference set is small. AutoHideSplashScreen is a boolean defaulting to true and indicates whether the splash screen hides automatically. SplashScreenDelay is a number defaulting to 3000 and is the amount of time in milliseconds to wait before automatically hiding the splash screen. FadeSplashScreen is a boolean defaulting to true, and setting it to false prevents the splash screen from fading in and out when its display state changes. FadeSplashScreenDuration is a float defaulting to 500 and specifies the number of milliseconds the fade effect takes to execute.

Each one has an example in the README, so a working config is four preference lines.

The delay and the fade share one budget

The most useful piece of documentation in the README is the note explaining how the fade duration interacts with the delay, and it is easy to misread.

FadeSplashScreenDuration is included into SplashScreenDelay. The README's worked example defines a delay of 3000 and a fade duration of 1000, and then spells out the timeline: at 00:00 the splash screen is shown, at 00:02 fading has started, and at 00:03 the splash screen is hidden. So the delay is the total visible time and the fade occupies the tail of it.

The second note is subtler. Turning the fading off via the FadeSplashScreen preference technically means a fading duration of zero, so in that example the overall splash screen delay is still three seconds. In other words, disabling the fade does not shorten the total time on screen, it just makes the screen appear and disappear without a transition.

The third note is a trap. The README says this timing only applies to application startup, and that you need to take the fading timeout into account when you manually show and hide the splash screen in your application's code. The example subtracts the fade duration from the splash duration before scheduling the hide:

    navigator.splashscreen.show();
    window.setTimeout(function () {
        navigator.splashscreen.hide();
    }, splashDuration - fadeDuration);

If you drive the splash screen manually and forget to subtract the fade, the screen disappears later than you intended, because the hide call has to land before the fade window closes.

There is also a legacy wrinkle in the delay unit. The README says the value used to be in seconds but is now milliseconds, so values less than 30 continue to be treated as seconds, and it calls this a deprecated patch that will disappear in some future version. A config written years ago with a value of 2 therefore still means two seconds, while a modern value of 3000 means three seconds, and a value of 30 is the ambiguous boundary.

Per-platform quirks: size, background and the absolute path rule

There is a second block of preferences for a specific platform, and the README labels it quirks. For the browser platform, the example is a platform element containing several preferences:

<platform name="browser">
    <preference name="SplashScreen" value="/images/browser/splashscreen.jpg" /> <!-- defaults to "/img/logo.png" -->
    <preference name="AutoHideSplashScreen" value="true" /> <!-- defaults to "true" -->
    <preference name="SplashScreenDelay" value="3000" /> <!-- defaults to "3000" -->
    <preference name="SplashScreenBackgroundColor" value="green" /> <!-- defaults to "#464646" -->
    <preference name="ShowSplashScreen" value="false" /> <!-- defaults to "true" -->
    <preference name="SplashScreenWidth" value="600" /> <!-- defaults to "170" -->
    <preference name="SplashScreenHeight" value="300" /> <!-- defaults to "200" -->
</platform>

Three things stand out. The screen is sized in pixels, with a default width of 170 and height of 200, and the example more than doubles the width and raises the height as well. The background colour is configurable and defaults to a dark grey. And there is a ShowSplashScreen preference, distinct from the auto hide setting, which can switch the whole thing off while leaving the delay and fade preferences in place.

The path rule is the practical gotcha. The README notes that the SplashScreen value should be absolute in order to work in a sub-page. The example path starts with a forward slash, and the reason is that a relative path is resolved against the current page, so the same configuration would break as soon as the user moves away from the entry page of the app.

That single sentence is the difference between a splash screen that appears reliably and one that disappears the moment a user opens a deep link, which is why it is worth reading the quirks block before copying any example config rather than after something breaks.

Where cordova-plugin-splashscreen is the wrong tool

The first wrong-tool case is an app targeting Android or iOS. The current supported platform list says Browser, and the package metadata platforms array agrees. The cordovaDependencies table still names android, windows and ios requirements for older Cordova versions, but that is a compatibility record for earlier releases rather than a statement about the current plugin, and treating it as one will cost you an afternoon.

The second is a native app that already has a native launch screen. On both major mobile platforms the operating system provides a launch screen, and. A plugin that paints a web-based splash screen on top of that produces a double flash on cold start, which reads as a bug even when everything is working.

The third is a modern app built on a different stack. Cordova is a wrapper around a web view, and a team that has moved to Capacitor, to a native framework, or to a progressive web app is not going to install a Cordova plugin to draw a rectangle during startup. The plugin is for Cordova projects.

The fourth is a product that cares about perceived performance in a measurable way. A splash screen that appears automatically before deviceready, holds for a fixed delay and then fades is a fixed cost added to every cold start. If your goal is to make the app feel faster, hiding the splash screen earlier, which means setting a shorter delay and calling hide() yourself once your app is ready, is a deliberate design decision. The plugin will happily hold a ten second delay, as the example in the README shows, and the README also says the delay has to include the fade, so the number you set is the number your users wait.

The fifth is a maintenance question. The repository has no GitHub releases, the version in the manifest is a development version at 7.0.0-dev, and the test script only runs the linter. The last push was on 2026-07-27 and the repository is not archived, so the work continues, but a plugin with a single supported platform and a lint-only test script is a small thing to depend on, and worth checking against your own release plan.

Editorial conclusion

cordova-plugin-splashscreen fits a Cordova team whose app targets the Browser platform and wants a launch screen that appears before deviceready and hides on a configurable delay, with the fade and sizing behaviour controlled from config.xml. It is the wrong choice for a Cordova app targeting Android or iOS in its current form, since the plugin now lists only the Browser platform. Before adopting it, check the cordova.platforms entry in the package metadata against your target, read the quirks block for your platform before assuming the defaults are what you want, and remember that the fade duration is counted inside the splash screen delay, so the two preferences have to be planned together.

Frequently asked questions

Official sources

1. apache/cordova-plugin-splashscreen on GitHub
2. Issues
3. License: Apache-2.0
4. README