Cordova - Splash Screen

Cordova - Splash Screen

A splash screen is the initial screen that appears when an application launches. The Cordova Splash Screen plugin (cordova-plugin-splashscreen) allows you to display a splash screen, typically an image, while your application’s web view is initializing.

Step 1 - Installing the Splash Screen Plugin

Install the plugin using the Cordova CLI in your project’s root directory:

your-cordova-project/ cordova plugin add cordova-plugin-splashscreen

Step 2 - Configuring the Splash Screen

Splash screen configuration is primarily done in your project’s config.xml file. You’ll need to add preferences and potentially platform-specific splash screen image declarations.

Basic Preferences in config.xml

Add the following preferences inside the main <widget> element in config.xml:

<!-- AutoHideSplashScreen: Set to false if you want to hide the splash screen manually -->
<preference name="AutoHideSplashScreen" value="true" />

<!-- SplashScreenDelay: Duration in milliseconds to show the splash screen (if AutoHideSplashScreen is true) -->
<preference name="SplashScreenDelay" value="3000" />

<!-- FadeSplashScreenDuration: Duration of the fade effect when hiding the splash screen (milliseconds) -->
<preference name="FadeSplashScreenDuration" value="500" />

<!-- SplashMaintainAspectRatio: If true, the splash screen image will not be stretched to fit the screen -->
<preference name="SplashMaintainAspectRatio" value="true" />

<!-- ShowSplashScreenSpinner: (Android, iOS) Whether to show a spinner on the splash screen -->
<preference name="ShowSplashScreenSpinner" value="true" />

<!-- SplashScreenSpinnerColor: (Android) Color of the spinner. Can be a color name or #HEX -->
<preference name="SplashScreenSpinnerColor" value="blue" />

The SplashScreen preference (e.g., <preference name="SplashScreen" value="screen" />) tells Cordova the base name of your splash screen image files. For example, if value="screen", Cordova will look for files like screen.png in various density-specific resource folders within each platform.

Adding Splash Screen Images

You need to provide splash screen images for different screen sizes, resolutions, and orientations. The exact locations and naming conventions vary by platform.

A common modern approach is to place a single, high-resolution source splash screen image (e.g., res/splash.png, at least 2732x2732px) and use a tool like cordova-res to automatically generate all the required sizes for Android and iOS. Install it with npm i -g cordova-res and run cordova-res --skip-config --copy in your project root.

Alternatively, you can manually create and place images in platform-specific directories (e.g., platforms/android/app/src/main/res/drawable-land-xhdpi/screen.png) or define them explicitly in config.xml using <splash> tags within <platform> blocks:

<platform name="android">
    <splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi"/>
    <splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi"/>
    <!-- ... more densities and orientations ... -->
</platform>
<platform name="ios">
    <splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
    <!-- ... more iOS sizes ... -->
</platform>

Ensure your image paths in src are relative to the project root and that the images exist.

Step 3 - Controlling Splash Screen Programmatically (Optional)

If you set <preference name="AutoHideSplashScreen" value="false" /> in config.xml, you need to hide the splash screen manually in your JavaScript code, typically after your app has initialized:

// In your onDeviceReady function or after app initialization
if (navigator.splashscreen) {
    navigator.splashscreen.hide();
}

You can also show it again if needed, although this is less common:

if (navigator.splashscreen) {
    navigator.splashscreen.show();
}

Testing the Splash Screen

After configuring config.xml and adding your images, rebuild your application for the desired platform:

your-cordova-project/ cordova build android
# or
your-cordova-project/ cordova build ios

Then, run the app on a device or emulator. You should see your splash screen displayed for the duration specified by SplashScreenDelay (if AutoHideSplashScreen is true), or until you hide it programmatically.

For example, if SplashScreenDelay is 3000, the splash screen will be visible for 3 seconds before the main app content appears. If SplashMaintainAspectRatio is true, the image won’t be distorted to fill the screen.

Best Practices

• Keep it Simple: Splash screens should be lightweight and display quickly.
• Provide All Sizes: Ensure you provide splash screens for all necessary resolutions and orientations to avoid black bars or poor scaling.
• Test Thoroughly: Test on various devices and OS versions.
• Consider cordova-res: This tool significantly simplifies managing splash screen (and icon) resources.