capacitor-splash-screen

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.
6. Verify (below).

Recommended config

// capacitor.config.ts
plugins: {
  SplashScreen: {
    launchAutoHide: false,     // hide from JS when the UI is ready
    launchFadeOutDuration: 200, // explicit: Capacitor 9 default on Android is 0
    backgroundColor: '#ffffff', // match the first web paint to avoid a flash
  },
},

import { SplashScreen } from '@capacitor/splash-screen';

// after the router's first view has rendered (e.g. in a root component's mounted/useEffect)
await SplashScreen.hide(); // optional: { fadeOutDuration: 300 }

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:

grep -rn "launchFadeOutDuration\|launchAutoHide" capacitor.config.*
grep -n "Theme.SplashScreen\|postSplashScreenTheme" android/app/src/main/res/values/styles.xml
/usr/libexec/PlistBuddy -c "Print :UILaunchStoryboardName" ios/App/App/Info.plist

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