Lottie Splash Screen

capacitor-lottie-splash-screen

Lottie Splash Screen plugin for Ionic Capacitor

Preview

Angular Example

Maintainers

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

Installation

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

or using pnpm

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

`typescript
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
},
...
};
`

$3

- 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.

`typescript
// 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

$3

`typescript
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

--------------------

$3

`typescript
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

--------------------

$3

`typescript
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

--------------------

$3

`typescript
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

--------------------

$3

`typescript
addListener(eventName: 'onAnimationEnd', listenerFunc: () => void) => Promise
`

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

--------------------

$3


#### LottieSplashScreenShowOptions

Options for showing the Lottie splash screen animation programmatically.

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


#### PluginListenerHandle

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