Using the Capacitor Splash Screen Plugin to Control Native Launch Images

When a Capacitor app starts, you can display a native launch image while the web code loads and then hide it programmatically once the app is ready. This prevents a blank screen or flash of unstyled content and gives a polished startup experience.

Installation and basic configuration

1. From the root of your Capacitor project, run:

npm i @capacitor/splash-screen
npx cap sync

This installs the plugin and copies the necessary native files into the Android and iOS projects.

1. Open capacitor.config.ts (or capacitor.config.json) and add the plugin under the plugins key:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'MyApp',
  webDir: 'www',
  plugins: {
    SplashScreen: {
      // Show the splash for 3 seconds unless we hide it earlier
      launchShowDuration: 3000,
      // Do not hide automatically; we will call hide() ourselves
      launchAutoHide: false
    }
  }
};

export default config;

The launchShowDuration value is in milliseconds and defines the maximum time the splash may stay visible if you never call hide(). Setting launchAutoHide: false gives you full control over when the splash disappears.

Worked example: showing and hiding the splash screen

Place the following code in a component that runs early in the app lifecycle, such as src/app/app.component.ts in an Angular project or the equivalent entry point for React/Vue.

import { Component } from '@angular/core';
import { Platform } from '@ionic/angular';
import { SplashScreen } from '@capacitor/splash-screen';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss']
})
export class AppComponent {
  constructor(private platform: Platform) {
    this.initializeApp();
  }

  async initializeApp() {
    await this.platform.ready();
    // At this point the web app is ready; hide the splash screen
    try {
      await SplashScreen.hide();
    } catch (e) {
      console.error('Failed to hide splash screen', e);
    }
  }
}

If you are not using Ionic, you can import Platform from @capacitor/core and listen for the resume or deviceready event instead.

Limits and common pitfalls

• Native‑only execution: The plugin has no effect when you run npm run dev or serve the web assets in a browser. You must build and run the native Android or iOS project (or use Capacitor’s web runtime with a native wrapper) to see the splash.
• Image resources: Android expects a splash image named splash in android/app/src/main/res/drawable-* folders. iOS requires a launch screen storyboard or image set named LaunchScreen. Missing or incorrectly sized resources cause the plugin to fall back to a blank screen.
• Calling hide() too early: If you invoke SplashScreen.hide() before the native side has finished initializing (e.g., outside platform.ready()), the splash may flash briefly or not appear at all.
• Incorrect launchAutoHide setting: Leaving the default true while also calling hide() can lead to a race condition where the splash disappears twice, producing a flicker.
• Outdated native dependencies: Using Capacitor Android/iOS versions ≤ 2.x with Splash Screen plugin ≥ 5.x can cause runtime errors such as ClassNotFoundException or Selector not recognized. Keep the core Capacitor packages in sync with the plugin version.

Practical verification steps

1. After installing the plugin and rebuilding (npx cap copy android or ios), launch the app on a device or emulator.
2. Observe that the splash image remains visible for at least the time defined by launchShowDuration (or until your code calls hide()).
3. Check the native logs for confirmation:
   • Android: run adb logcat | grep SplashScreenPlugin and look for a line like SplashScreenPlugin: hide called.
   • iOS: in Xcode’s console, filter for SplashScreen and verify the hide callback appears.
4. To test the automatic‑hide behavior, temporarily set launchAutoHide: true and remove the manual SplashScreen.hide() call. The splash should disappear automatically after the configured duration.