@attarchi/react-native-lottie-splash-screen

Fork of react-native-splash-screen with animated splash screen using Airbnb Lottie. Works on iOS and Android.

Acknowledgement

Huge thanks to the original authors and contributors of react-native-lottie-splash-screen. The original package became outdated and PRs/issues went unanswered. To keep it maintained and compatible with new React Native versions, this updated package is published under my namespace as @attarchi/react-native-lottie-splash-screen.

Contents

• Version Compatibilities
• Examples
• Installation - React Native Bare ≥ 0.77)
• Installation - Expo (Bare Workflow)
• Usage
• API
• Upgrade v2 → v3
• Contribution

Versions Compatibilities

| React Native | react-native-lottie-splash-screen | |---|---| | >= 0.77 | 3.x | | >= 0.70 & < 0.77 | 2.x | | < 0.70 | 1.x |

Warning: Version 3.x has no backward compatibility. You need to follow the upgrade instructions.

Examples

You can clone this project and run the examples with these commands:

yarn install

# Run react-native bare 79 example
yarn bare:install
yarn bare:ios
yarn bare:android

# Run the EXPO example
yarn expo:install
yarn expo:ios
yarn expo:android

Installation (React Native ≥ 0.77)

Follow these steps in order.

1) Install packages

yarn add @attarchi/react-native-lottie-splash-screen [email protected]

cd ios && bundle install && bundle exec pod install

2) iOS setup

1. Add your Lottie JSON (e.g. loading.json) to the Xcode project and include it in the app target.

2. Open AppDelegate.swift in the ios folder and add the setup call:

import UIKit
...
import SplashScreen // <- Add this line

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(...) -> Bool {
    ...

    // Before return, add this:
    // Setup Lottie splash screen using the SplashScreen module
    SplashScreen.setupLottieSplash(in: window, lottieName: "loading", backgroundColor: UIColor.white, forceToCloseByHideMethod: false)

    return true
  }
}

3. Remove the default iOS launch screen.

   By default, iOS displays the launch storyboard before your app is ready. To ensure a seamless transition to your Lottie splash, you should make the launch screen blank or match the first frame of your Lottie animation.

   To make it blank, open the LaunchScreen.storyboard file in the ios folder and remove the <subviews> section from the main <view>. This will prevent any default labels or images from appearing.

4. Build iOS once to verify.

3) Android setup

1. Create android/app/src/main/res/layout/launch_screen.xml:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@color/windowSplashScreenBackground">
  <com.airbnb.lottie.LottieAnimationView
      android:id="@+id/lottie"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      app:lottie_rawRes="@raw/loading"
      app:lottie_autoPlay="false"
      app:lottie_loop="false" />
</LinearLayout>

2. Place your Lottie JSON at android/app/src/main/res/raw/loading.json.
3. Ensure styles exist at android/app/src/main/res/values/styles.xml:

<resources>
  <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
    <item name="android:editTextBackground">@drawable/rn_edit_text_material</item>
    <item name="android:statusBarColor">#ffffff</item>
    <!-- Add the below line: -->
    <item name="android:windowDisablePreview">true</item>
  </style>

  <!-- Also, copy these lines to you project. -->
  <style name="SplashScreen_SplashAnimation">
    <item name="android:windowExitAnimation">@android:anim/fade_out</item>
  </style>

  <style name="SplashScreen_SplashTheme" parent="Theme.AppCompat.NoActionBar">
    <item name="android:windowAnimationStyle">@style/SplashScreen_SplashAnimation</item>
    <item name="windowActionBarOverlay">false</item>
    <item name="android:windowTranslucentStatus">true</item>
  </style>
  <!-- End of copy -->
</resources>

4. Ensure color exists at android/app/src/main/res/values/colors.xml:

<resources>
  <color name="windowSplashScreenBackground">#ffffff</color>
</resources>

5. Update MainActivity.kt:

...
import com.facebook.react.defaults.DefaultReactActivityDelegate
import org.devio.rn.splashscreen.SplashScreen // <- Add this line
import android.os.Bundle

class MainActivity : ReactActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Add the below line at the bottom of the onCreate function: 
    SplashScreen.show(this, R.style.SplashScreen_SplashTheme, R.id.lottie, false)
  }

...

6. Build Android to verify.

Expo Bare Workflow

This package supports Expo Bare projects. It does not work in the Expo Go App.

Follow these steps.

1) Prebuild native projects

If you have a Expo project and you want a real lottie splash screen you have to eject your project to bare workflow with these commands:

npx expo prebuild -p android
npx expo prebuild -p ios

2) Install and configure

• Run the Installation steps above (packages, iOS and Android setup).
• Android manifest: set your MainActivity theme to @style/AppTheme (not Expo’s splash theme).
• In MainActivity.kt, ensure:

setTheme(R.style.AppTheme)
super.onCreate(null)
SplashScreen.show(this, R.style.SplashScreen_SplashTheme, R.id.lottie, false) // This line

• iOS: Add your Lottie JSON and call SplashScreen.setupLottieSplash(...) in AppDelegate.swift as shown above.

3) Run on devices/simulators

yarn android
yarn ios

Use these instead of yarn start to see the native splash overlay. See this commit for a working Expo example configuration.

Usage

1. Import in your app entry and hide once the app is ready:

import { useEffect } from "react";
import LottieSplashScreen from "@attarchi/react-native-lottie-splash-screen";

export default function App() {
  useEffect(() => {
    // Hide the splash screen when your app is ready.
    // The optional chaining (?.) is important for Expo projects.
    LottieSplashScreen?.hide();
  }, []);
  return null;
}

API

| Method | Type | Optional | Description | | ------ | -------- | -------- | ----------- | | hide() | function | false | Closes the Lottie splash overlay |

Upgrade v2 → v3 (React Native ≥ 0.77)

You can see all needed changes together in these commits:

• iOS
• Android

1. Update packages:

yarn add @attarchi/react-native-lottie-splash-screen@^3 lottie-react-native@^7
cd ios && bundle exec pod install

2. iOS changes:
   • Remove any previous Dynamic.swift and bridging-header usage.
   • Add your Lottie JSON to the app target if not present.
   • Add following codes in AppDelegate.swift:

import SplashScreen
SplashScreen.setupLottieSplash(in: window, lottieName: "loading", backgroundColor: UIColor.white, forceToCloseByHideMethod: false)

3. Android changes:
   • Replace any SplashScreen.show(this, R.style.SplashScreen_SplashTheme, R.id.lottie) with:

SplashScreen.show(this, R.style.SplashScreen_SplashTheme, R.id.lottie, false)

• Remove SplashScreen.setAnimationFinished(true) from onCreate.
• Ensure launch_screen.xml uses app:lottie_autoPlay="false" and the layout/background/styles/colors from the Installation section.

4. JS:
   • Keep LottieSplashScreen?.hide() when your app is ready.

Contribution

Issues and PRs are welcome. The fastest way to receive help is to include a minimal repro (you can base it on the examples in this repo).

MIT Licensed