MCPInstall

capacitor-splash-screen

by cap-goCode Quality & Workflow

Configures and debugs launch splash screens in Capacitor apps with @capacitor/splash-screen and @capacitor/assets - launchAutoHide, SplashScreen.hide(), launchFadeOutDuration (Android default changed 200 - 0 in Capacitor 9), Android 12+ SplashScreen API theme (Theme.SplashScreen, windowSplashScreenAnimatedIcon), iOS LaunchScreen.storyboard + Splash.imageset, and Capacitor 8.5 UIScene/SceneDelegate effects (window created in code, Main.storyboard no longer supplies the root view controller). Use for white/black flash at launch, splash never hiding, cropped/tiny Android 12 icon, dark-mode splash, or regenerating icons and splash assets. Do not use for status/navigation bar color and insets (safe-area-handling), the UIScene migration itself (capacitor-uiscene-migration), or startup performance profiling (capacitor-performance).

Installs
1.1K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-splash-screen
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads capacitor-splash-screen automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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)

PhaseiOSAndroid 12+Android <= 11
OS launch screen (before any code)LaunchScreen.storyboard (UILaunchStoryboardName), image Splash in Assets.xcassets/Splash.imagesetSystem SplashScreen API: theme AppTheme.NoActionBarLaunch with Theme.SplashScreen parent - icon + background color onlyandroidx.core:core-splashscreen compat, or android:background drawable
Plugin splash (until hide())Plugin overlay on the bridge viewSame system splash held via the APIPlugin 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

VersionChange
4Android uses the Android 12 SplashScreen API + compat library
7SplashScreenShowOptions / SplashScreenHideOptions types removed -> ShowOptions / HideOptions
8coreSplashScreenVersion = '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.
9Android 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 / messageCauseFix
Splash stays foreverlaunchAutoHide: 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 0Set launchFadeOutDuration: 200
UI changes right after hide() not visible (Android, pre-9)200 ms fade blocked updatesSet launchFadeOutDuration: 0
Android 12+ shows small icon, image croppedOS splash is icon-only by designProvide adaptive icon-safe artwork; tune windowSplashScreenAnimatedIcon
Android 12/12L no splash from third-party launchers or Android StudioPlatform bug fixed in Android 13Test from the stock launcher
error: resource drawable/splash not foundandroidSplashResourceName or styles reference a missing drawableRegenerate assets or fix the name in both config and styles.xml
AAPT: error: style attribute 'attr/windowSplashScreenAnimatedIcon' not foundcore-splashscreen dependency missingRestore implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
iOS black screen after 8.5 scene adoptionNo window created in SceneDelegateSee iOS notes / capacitor-uiscene-migration
Old splash still shows on iOSLaunch screen cacheDelete app, reboot device if needed, reinstall

Resources

FAQ

What does the capacitor-splash-screen skill do?

Configures and debugs launch splash screens in Capacitor apps with @capacitor/splash-screen and @capacitor/assets - launchAutoHide, SplashScreen.hide(), launchFadeOutDuration (Android default changed 200 - 0 in Capacitor 9), Android 12+ SplashScreen API theme (Theme.SplashScreen, windowSplashScreenAnimatedIcon), iOS LaunchScreen.storyboard + Splash.imageset, and Capacitor 8.5 UIScene/SceneDelegate effects (window created in code, Main.storyboard no longer supplies the root view controller). Use for white/black flash at launch, splash never hiding, cropped/tiny Android 12 icon, dark-mode splash, or regenerating icons and splash assets. Do not use for status/navigation bar color and insets (safe-area-handling), the UIScene migration itself (capacitor-uiscene-migration), or startup performance profiling (capacitor-performance).

How do I install capacitor-splash-screen?

Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-splash-screen in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capacitor-splash-screen/ (personal) or .claude/skills/capacitor-splash-screen/ (project).

Which AI agents can use capacitor-splash-screen?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is capacitor-splash-screen safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains capacitor-splash-screen?

It is published by cap-go in cap-go/capgo-skills. It has 1,122 recorded installs.

More from cap-go/capgo-skills

View all →

capacitor-best-practices

cap-go/capgo-skills

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

Code Quality & Workflow2.7K installs

ionic-design

cap-go/capgo-skills

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

Frontend & Design1.6K installs

capacitor-plugins

cap-go/capgo-skills

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

Frontend & Design1.6K installs

debugging-capacitor

cap-go/capgo-skills

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

Code Quality & Workflow1.3K installs

capacitor-testing

cap-go/capgo-skills

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor

Testing & QA1.3K installs

safe-area-handling

cap-go/capgo-skills

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

Mobile1.3K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs