Guide to configuring splash screens in Capacitor apps including asset generation, animation, and programmatic control. Use this skill when users need to customize their app launch experience.

Splash Screen in Capacitor When to Use TRIGGER when: Configuring or regenerating splash / icon assets ( npx capacitor assets generate ) Splash never disappears, disappears too early, or flashes white/black before the web app paints Android 12+ shows a small cropped icon on a solid color instead of the full image Upgrading to Capacitor 9 and the Android fade out animation vanished iOS shows a black screen after adding SceneDelegate.swift (8.5+) Do not use: Status bar / navigation bar styling and edge to edge insets: safe area handling Migrating AppDelegate to SceneDelegate: capacitor uiscene migration Slow first paint / bundle size: capacitor performance Icon requirements for store submission: capacitor app store How launch works (decide what to edit) Phase iOS Android 12+ Android <= 11 OS launch screen (before any code) LaunchScreen.storyboard ( UILaunchStoryboardName ), image Splash in Assets.xcassets/Splash.imageset System SplashScreen API: theme AppTheme.NoActionBarLaunch with Theme.SplashScreen parent icon + background color only androidx.core:core splashscreen compat, or android:background drawable Plugin splash (until hide() ) Plugin overlay on the bridge view Same system splash held via the API Plugin ImageView / Dialog ( androidSplashResourceName , androidScaleType ) Most androidScaleType , showSpinner , splashFullScreen , layoutName , useDialog , backgroundColor options do not apply on Android 12+ launch (the OS draws it). They only affect show() and pre 12 devices. Workflow 1. Inspect : capacitor.config. plugins.SplashScreen , android/app/src/main/res/values/styles.xml , android/variables.gradle ( coreSplashScreenVersion ), ios/App/App/Info.plist , ios/App/App/SceneDelegate.swift , assets/ or resources/ folder. 2. Install : npm install @capacitor/splash screen && npx cap sync . 3. Assets : put sources in assets/ ( icon only.png , icon foreground.png , icon background.png , splash.png , splash dark.png ; splash = 2732x2732, icons = 1024x1024), then npm install D @capacitor/assets && npx capacitor assets generate ( ios , android , pwa to scope). Keep the logo inside the center ~1/3 so Android 12+ circular masking does not crop it. 4. Hide deliberately : set launchAutoHide: false and call hide() after the first meaningful render (below). 5. Android 12+ tuning if needed: [references/android 12 splash.md](references/android 12 splash.md). 6. Verify (below). Recommended config Traps: With launchAutoHide: false , a JS crash before hide() leaves the app stuck on the splash. Add a fallback: setTimeout(() = SplashScreen.hide(), 8000) . Default when auto hiding is 500 ms ( launchShowDuration ). Long fixed durations hurt perceived startup; hide on readiness instead. Set <body / root background to the splash background color, or the gap between native splash and first web paint flashes white (dark mode: black). Live updates ( capgo live updates ): call notifyAppReady() independently of hide() ; do not gate one on the other. Version notes Version Change 4 Android uses the Android 12 SplashScreen API + compat library 7 SplashScreenShowOptions / SplashScreenHideOptions types removed ShowOptions / HideOptions 8 coreSplashScreenVersion = '1.2.0' 8.5 (iOS) UIScene template creates the window and CAPBridgeViewController in SceneDelegate ; Main.storyboard no longer supplies the root view controller. LaunchScreen.storyboard is unchanged and still required. 9 Android launchFadeOutDuration default 200 0 (the old default could block UI changes right after hide() ). Set 200 explicitly to keep the fade. iOS notes (Capacitor 8.5+ scenes) Keep UILaunchStoryboardName = LaunchScreen in Info.plist. Apple requires a launch storyboard; deleting it causes letterboxed / wrong size rendering. Do not add views or a custom view controller to Main.storyboard expecting them to show: the 8.5 SceneDelegate sets window.rootViewController = CAPBridgeViewController() in code. Put a custom CAPBridgeViewController subclass there instead. Black screen right after launch with a scene manifest = SceneDelegate creates no window (missing window = UIWindow(windowScene:) + makeKeyAndVisible() ) or UISceneDelegateClassName points to a missing class. Fix with capacitor uiscene migration . The storyboard is cached by iOS. After changing it, delete the app from the device/simulator and reinstall. On resizable windows / iPad / foldables the launch storyboard must use Auto Layout constraints, not fixed frames (see capacitor ios resizability if present). Verification 1. npx cap sync then a clean native build ( Product Clean Build Folder in Xcode; ./gradlew clean in android/ ). 2. Delete and reinstall the app (both platforms cache launch screens). 3. Cold launch on: iOS device light + dark mode, Android 12+ device, Android <= 11 emulator (if minSdk allows; Capacitor 9 minSdk is 26). 4. Confirm: no white/black flash, splash hides once the first screen is visible, fade matches the configured duration. 5. Grep for leftovers: Error Handling Symptom / message Cause Fix Splash stays forever launchAutoHide: false and hide() never runs (JS error, wrong import, called before plugin load) Check web console; add timeout fallback Fade out gone after Capacitor 9 upgrade (Android) Default launchFadeOutDuration is now 0 Set launchFadeOutDuration: 200 UI changes right after hide() not visible (Android, pre 9) 200 ms fade blocked updates Set launchFadeOutDuration: 0 Android 12+ shows small icon, image cropped OS splash is icon only by design Provide adaptive icon safe artwork; tune windowSplashScreenAnimatedIcon Android 12/12L no splash from third party launchers or Android Studio Platform bug fixed in Android 13 Test from the stock launcher error: resource drawable/splash not found androidSplashResourceName or styles reference a missing drawable Regenerate assets or fix the name in both config and styles.xml AAPT: error: style attribute 'attr/windowSplashScreenAnimatedIcon' not found core splashscreen dependency missing Restore implementation "androidx.core:core splashscreen:$coreSplashScreenVersion" iOS black screen after 8.5 scene adoption No window created in SceneDelegate See iOS notes / capacitor uiscene migration Old splash still shows on iOS Launch screen cache Delete app, reboot device if needed, reinstall Resources Plugin API: https://capacitorjs.com/docs/apis/splash screen Splash screens and icons guide: https://capacitorjs.com/docs/guides/splash screens and icons Updating to 9.0: https://capacitorjs.com/docs/updating/9 0 Android SplashScreen API: https://developer.android.com/develop/ui/views/launch/splash screen

capacitor-splash-screen