cap-go/capgo-skills/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)

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

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

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