Preview

Angular Example

Maintainers

| Maintainer | GitHub | Social | LinkedIn | | ---------------------- | ------------------------------------- | --------------------------------- | ------------------------------------------------------------------ | | Luan Freitas (ludufre) | ludufre | @ludufre | Luan Freitas |

Installation

npm install capacitor-lottie-splash-screen
npx cap sync

# or using pnpm
pnpm add capacitor-lottie-splash-screen
npx cap sync

Add to capacitor.config.ts or capcitor.config.json

const config: CapacitorConfig = {
  ...
  LottieSplashScreen: {
    enabled: true, // Enables the Lottie splash (can still be shown manually)
    animationLight: 'public/assets/[path/to.json]', // REQUIRED: Path to Lottie file for light mode
    animationDark: 'public/assets/[path/to.json]',   // Optional: Lottie for dark mode (defaults to animationLight)
    backgroundLight: '#FFFFFF', // Optional: background color in light mode (default: #FFFFFF)
    backgroundDark: '#000000', // Optional: background color in dark mode (default: #000000)
    autoHide: false, // Auto-hide after animation ends (if false, call appLoaded manually)
    loop: false,     // Loop animation (not recommended with autoHide: true)
  },
  SplashScreen: {
    launchAutoHide: true, // Disables @capacitor/splash-screen
    launchShowDuration: 0
  },
  ...
};

⚠️ Important Notes!

• autoHide true:

  • The splash screen will hide automatically after the animation ends.
  • If you call LottieSplashScreen.appLoaded() before the animation ends, it will wait until the animation finishes.
  • Calling LottieSplashScreen.hide() will hide it immediately without waiting for the end.

• autoHide false (default):

  • You must call LottieSplashScreen.appLoaded() to hide the splash screen after your app is loaded. If you do not call it, the splash screen will remain visible indefinitely with last frame displayed.

• Loop behavior:

  • If loop is true, the animation will continue looping until LottieSplashScreen.appLoaded() is called (which stops it immediately).
  • To play the animation only once, set loop to false (default behavior).
  • Tip: If loop: true and autoHide: true, the plugin will disable looping automatically (they’re incompatible). Use loop: true only when you’re controlling the splash manually.

• Manual display:

  • When calling LottieSplashScreen.show(), the splash screen appears and starts playing the animation immediately.
  • You must call LottieSplashScreen.hide() to remove the splash screen; the animation end is not waited for.

Example

See the Angular Example for a complete example of how to use the plugin in an Ionic Angular application.

Call LottieSplashScreen.appLoaded(); when the App is ready.

// Splash screen will only close after this call and the animation ends unless you set "autoHide: true" which will hide it automatically.
import { Platform } from '@ionic/angular';
import { LottieSplashScreen } from 'capacitor-lottie-splash-screen';

constructor(private platform: Platform) {
  this.platform.ready().then(() => {
    // Call this AFTER the app is ready and bootstrapped
    LottieSplashScreen.appLoaded();
  });
}

// Another way with Angular provideAppInitializer() (reaplces APP_INITIALIZER) to ensure the app is loaded before proceeding
bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideAppInitializer(async () => {
      await inject(...).init(); // Your initialization logic here
      await LottieSplashScreen.appLoaded();
    }),
    ...
  ],
})...

// Programmatically show the splash screen
LottieSplashScreen.show();

// Programmatically hide the splash screen (without waiting for animation end)
LottieSplashScreen.hide();

// Check if the splash screen is animating
LottieSplashScreen.isAnimating().then((result) => {
  console.log('Is animating:', result.isAnimating);
});

// Add a listener for the animation end event
LottieSplashScreen.addListener('onAnimationEnd', () => {
  console.log('Animation ended');
});

Highly Inspired / Credits

• https://github.com/Get-Local/capacitor-lottie-splash-screen
• https://github.com/MorphoodInc/capacitor-lottie-splash-screen
• https://github.com/muhammadosmanali/capacitor-lottie-splash-screen

API

• appLoaded()
• show(...)
• hide()
• isAnimating()
• addListener('onAnimationEnd', ...)
• Interfaces

appLoaded()

appLoaded() => void

Notify the plugin that the app has fully loaded.

Call this method as early as possible after your app has bootstrapped. It allows the plugin to gracefully finish or remove the splash animation overlay. If the splash is configured to loop, this will forcibly stop it.

Since: 7.0.0

show(...)

show(options?: LottieSplashScreenShowOptions | undefined) => void

Programmatically show the splash screen animation again.

This is useful for scenarios like restarting the splash for a specific action or navigation flow.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | LottieSplashScreenShowOptions |

Since: 7.0.0

hide()

hide() => void

Hide the splash screen immediately, skipping the animation completion.

Use this when you want to forcefully remove the splash overlay (e.g., on error or timeout).

Since: 7.0.0

isAnimating()

isAnimating() => Promise<{ isAnimating: boolean; }>

Check if the splash animation is currently running.

Returns a boolean wrapped in a promise indicating the splash screen’s active state.

Returns: Promise<{ isAnimating: boolean; }>

Since: 7.0.0

addListener('onAnimationEnd', ...)

addListener(eventName: 'onAnimationEnd', listenerFunc: () => void) => Promise<PluginListenerHandle>

Register a listener for the splash animation end event.

This event is triggered once the animation finishes and the overlay is removed.

| Param | Type | Description | | ------------------ | ----------------------------- | ------------------------------------------------------------- | | eventName | 'onAnimationEnd' | - Must be 'onAnimationEnd' | | listenerFunc | () => void | - A callback function that runs when the animation completes. |

Returns: Promise<PluginListenerHandle>

Since: 7.0.0

Interfaces

LottieSplashScreenShowOptions

Options for showing the Lottie splash screen animation programmatically.

| Prop | Type | | ---------------- | -------------------- | | animation | string | | isDarkMode | boolean |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |