@amjed.gabteni/capacitor-lottie-splashscreen

Capacitor plugin to show a native full-screen Lottie splash overlay on iOS and Android.

Install

npm install @amjed.gabteni/capacitor-lottie-splashscreen
npx cap sync

Platform install help

• Install overview
• iOS install help
• Android install help

Project files

• Contributing guide
• Code of conduct
• Security policy
• License
• GitHub setup
• npm org publish guide

iOS setup

1. Add your animation JSON file to your iOS app bundle (for example splash.json).
2. Ensure it is copied into the app target.

Android setup

1. Place your animation JSON file in android/app/src/main/assets/ (for example splash.json).
2. Rebuild and sync Capacitor.

Launch config

Configure launch behavior in capacitor.config.ts:

plugins: {
  LottieSplashscreen: {
    launchAutoShow: true,
    launchAnimationName: 'splash',
    launchLoop: true,
    launchSpeed: 1,
    launchBackgroundColor: '#000000',
    launchAutoHideMs: 2500,
    launchSafetyHideMs: 7000,
  },
}

Notes:

• launchAutoShow: enables automatic splash on app launch.
• launchAutoHideMs: set 0 to keep the splash visible until hide() is called.
• launchSafetyHideMs: force-hide safety timeout to avoid stuck overlays.
• launchAnimationName: accepts either splash, splash.json, or bundle paths like public/splash.

API

• show(...)
• hide(...)
• preload(...)
• setAnimation(...)
• Interfaces

show(...)

show(options?: ShowOptions | undefined) => any

Show the native Lottie splash overlay.

| Param | Type | | ------------- | --------------------------------------------------- | | options | ShowOptions |

Returns: any

hide(...)

hide(options?: HideOptions | undefined) => any

Hide the native Lottie splash overlay.

| Param | Type | | ------------- | --------------------------------------------------- | | options | HideOptions |

Returns: any

preload(...)

preload(options: PreloadOptions) => any

Preload an animation composition for faster startup display.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | PreloadOptions |

Returns: any

setAnimation(...)

setAnimation(options: SetAnimationOptions) => any

Update the default animation used by future show() calls.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | SetAnimationOptions |

Returns: any

Interfaces

ShowOptions

| Prop | Type | Description | | --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | | animationName | string | Animation file name from the native app bundle/assets. You can pass either splash or splash.json. | | loop | boolean | Whether the animation should loop forever. | | speed | number | Playback speed where 1 is normal speed. | | backgroundColor | string | Background color as CSS hex (for example #0f172a). | | autoHideMs | number | Auto-hide timeout in milliseconds. Set 0 or omit to keep splash visible until hide() is called. |

HideOptions

| Prop | Type | Description | | --------------- | ------------------- | ---------------------------------- | | fadeOutMs | number | Fade out duration in milliseconds. |

PreloadOptions

| Prop | Type | Description | | ------------------- | ------------------- | --------------------------------------- | | animationName | string | Animation file name from native assets. |

SetAnimationOptions

| Prop | Type | Description | | ------------------- | ------------------- | --------------------------------------- | | animationName | string | Animation file name from native assets. |

Usage

import { LottieSplashscreen } from '@amjed.gabteni/capacitor-lottie-splashscreen';

await LottieSplashscreen.preload({ animationName: 'splash' });
await LottieSplashscreen.show({
  animationName: 'splash',
  loop: true,
  speed: 1,
  backgroundColor: '#020617',
});

// after app bootstrap
await LottieSplashscreen.hide({ fadeOutMs: 220 });