🚀 react-native-bootsplash

Show a bootsplash during app startup. Hide it when you are ready.

Support

For 0.59-, you should use jetify -r

Installation

1$ npm install --save react-native-bootsplash
2# --- or ---
3$ yarn add react-native-bootsplash

Don't forget going into the ios directory to execute a pod install.

🆘 Manual linking

Because this package targets React Native 0.60.0+, you will probably don't need to link it manually. Otherwise if it's not the case, follow this additional instructions:

1target 'YourAwesomeProject' do
2  # …
3  pod 'RNBootSplash', :path => '../node_modules/react-native-bootsplash'
4end

1include ':react-native-bootsplash'
2project(':react-native-bootsplash').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-bootsplash/android')

1dependencies {
2  // ...
3  implementation project(':react-native-bootsplash')
4}

1import com.zoontek.rnbootsplash.RNBootSplashPackage; // <- add the RNBootSplashPackage import
2
3public class MainApplication extends Application implements ReactApplication {
4
5  // …
6
7  @Override
8  protected List<ReactPackage> getPackages() {
9    @SuppressWarnings("UnnecessaryLocalVariable")
10    List<ReactPackage> packages = new PackageList(this).getPackages();
11    // …
12    packages.add(new RNBootSplashPackage());
13    return packages;
14  }
15
16  // …
17}

Setup

Assets generation

In order to speed up the setup, we provide a CLI to generate assets, create the Android Drawable XML file and the iOS Storyboard file automatically ✨.

1$ npx react-native generate-bootsplash --help
2# --- or ---
3$ yarn react-native generate-bootsplash --help

The command can take multiple arguments:

1react-native generate-bootsplash <logoPath>
2
3Generate a launch screen using an original logo file
4
5Options:
6  --background-color <color>  color used as launch screen background (in hexadecimal format) (default: "#fff")
7  --logo-width <width>        logo width at @1x (in dp - we recommand approximately ~100) (default: 100)
8  --assets-path [path]        path to your static assets directory (useful to require the logo file in JS)
9  --flavor <flavor>           [android only] flavor build variant (outputs in an android resource directory other than "main")
10  -h, --help                  output usage information

Full command usage example

1yarn react-native generate-bootsplash assets/bootsplash_logo_original.png \
2  --background-color=F5FCFF \
3  --logo-width=100 \
4  --assets-path=assets \
5  --flavor=main

This tool relies on the naming conventions that are used in the /example project and will therefore create the following files:

1android/app/src/main/res/drawable/bootsplash.xml
2android/app/src/main/res/values/colors.xml (creation and edition)
3android/app/src/main/res/mipmap-hdpi/bootsplash_logo.png
4android/app/src/main/res/mipmap-mdpi/bootsplash_logo.png
5android/app/src/main/res/mipmap-xhdpi/bootsplash_logo.png
6android/app/src/main/res/mipmap-xxhdpi/bootsplash_logo.png
7android/app/src/main/res/mipmap-xxxhdpi/bootsplash_logo.png
8
9ios/YourProjectName/BootSplash.storyboard
10ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo.png
11ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo@2x.png
12ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo@3x.png
13
14# Only if --assets-path was specified
15assets/bootsplash_logo.png
16assets/bootsplash_logo@1,5x.png
17assets/bootsplash_logo@2x.png
18assets/bootsplash_logo@3x.png
19assets/bootsplash_logo@4x.png

iOS

⚠️ Only .storyboard files are supported (Apple has deprecated other methods in April 2020).

Edit the ios/YourProjectName/AppDelegate.m file:

1#import "AppDelegate.h"
2
3#import <React/RCTBridge.h>
4#import <React/RCTBundleURLProvider.h>
5#import <React/RCTRootView.h>
6
7#import "RNBootSplash.h" // <- add the header import
8
9@implementation AppDelegate
10
11- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
12{
13  // …
14  rootViewController.view = rootView;
15  self.window.rootViewController = rootViewController;
16  [self.window makeKeyAndVisible];
17
18  [RNBootSplash initWithStoryboard:@"BootSplash" rootView:rootView]; // <- initialization using the storyboard file name
19
20  return YES;
21}

Set the BootSplash.storyboard as launch screen file:

Drag and drop the file	Create folder reference	Set as Launch Screen File

Android

1. Edit the android/app/src/main/java/com/yourprojectname/MainActivity.java file:

1import android.os.Bundle; // <- add this necessary import
2
3import com.facebook.react.ReactActivity;
4import com.zoontek.rnbootsplash.RNBootSplash; // <- add this necessary import
5
6public class MainActivity extends ReactActivity {
7
8  // …
9
10  @Override
11  protected void onCreate(Bundle savedInstanceState) {
12    super.onCreate(savedInstanceState);
13    RNBootSplash.init(R.drawable.bootsplash, MainActivity.this); // <- display the generated bootsplash.xml drawable over our MainActivity
14  }

As Android will not create our main activity before launching the app, we need to display a different activity at start, then switch to our main one.

2. Edit the android/app/src/main/res/values/styles.xml file:

1<resources>
2
3  <!-- Base application theme -->
4  <style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
5    <!-- Your base theme customization -->
6  </style>
7
8  <!-- Add the following lines (BootTheme should inherit from AppTheme) -->
9  <style name="BootTheme" parent="AppTheme">
10    <!-- set the generated bootsplash.xml drawable as activity background -->
11    <item name="android:background">@drawable/bootsplash</item>
12  </style>
13
14</resources>

3. Edit the android/app/src/main/AndroidManifest.xml file:

1<manifest xmlns:android="http://schemas.android.com/apk/res/android"
2  package="com.rnbootsplashexample">
3
4  <!-- … -->
5
6  <application
7    android:name=".MainApplication"
8    android:label="@string/app_name"
9    android:icon="@mipmap/ic_launcher"
10    android:roundIcon="@mipmap/ic_launcher_round"
11    android:allowBackup="false"
12    android:theme="@style/AppTheme">
13
14    <activity
15      android:name=".MainActivity"
16      android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
17      android:label="@string/app_name"
18      android:windowSoftInputMode="adjustResize"
19      android:exported="true"
20      android:launchMode="singleTask">
21      <!-- ⚠️ add android:exported="true" and android:launchMode="singleTask" above -->
22      <!-- remove the <intent-filter> from .MainActivity -->
23    </activity>
24
25    <!-- add the following lines (use the theme you created at step 2) -->
26    <activity
27      android:name="com.zoontek.rnbootsplash.RNBootSplashActivity"
28      android:theme="@style/BootTheme"
29      android:launchMode="singleTask">
30      <intent-filter>
31        <action android:name="android.intent.action.MAIN" />
32        <category android:name="android.intent.category.LAUNCHER" />
33      </intent-filter>
34    </activity>
35
36    <!-- … -->
37
38  </application>
39
40</manifest>

API

hide()

Method type

1type hide = (config?: { fade?: boolean }) => Promise<void>;

Usage

1import RNBootSplash from "react-native-bootsplash";
2
3RNBootSplash.hide(); // immediate
4RNBootSplash.hide({ fade: true }); // fade

show()

Method type

1type show = (config?: { fade?: boolean }) => Promise<void>;

Usage

1import RNBootSplash from "react-native-bootsplash";
2
3RNBootSplash.show(); // immediate
4RNBootSplash.show({ fade: true }); // fade

getVisibilityStatus()

Method type

1type VisibilityStatus = "visible" | "hidden" | "transitioning";
2type getVisibilityStatus = () => Promise<VisibilityStatus>;

Usage

1import RNBootSplash from "react-native-bootsplash";
2
3RNBootSplash.getVisibilityStatus().then((status) => console.log(status));

Real world example

1import React, { useEffect } from "react";
2import { Text } from "react-native";
3import RNBootSplash from "react-native-bootsplash";
4
5function App() {
6  useEffect(() => {
7    const init = async () => {
8      // …do multiple sync or async tasks
9    };
10
11    init().finally(async () => {
12      await RNBootSplash.hide({ fade: true });
13      console.log("Bootsplash has been hidden successfully");
14    });
15  }, []);
16
17  return <Text>My awesome app</Text>;
18}

🤙 A more complex example is available in the /example folder.

Guides

Handle deep linking (on Android)

If you want to correctly handle deep linking with this package, you should edit the android/app/src/main/AndroidManifest.xml file like this:

1<manifest xmlns:android="http://schemas.android.com/apk/res/android"
2  package="com.rnbootsplashexample">
3
4  <!-- … -->
5
6  <application
7    android:name=".MainApplication"
8    android:label="@string/app_name"
9    android:icon="@mipmap/ic_launcher"
10    android:roundIcon="@mipmap/ic_launcher_round"
11    android:allowBackup="false"
12    android:theme="@style/AppTheme">
13
14    <activity
15      android:name=".MainActivity"
16      android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
17      android:label="@string/app_name"
18      android:windowSoftInputMode="adjustResize"
19      android:exported="true"
20      android:launchMode="singleTask">
21      <!-- ⚠️ add android:exported="true" and android:launchMode="singleTask" above -->
22      <!-- remove the <intent-filter> from .MainActivity -->
23    </activity>
24
25    <activity
26      android:name="com.zoontek.rnbootsplash.RNBootSplashActivity"
27      android:theme="@style/BootTheme"
28      android:launchMode="singleTask">
29      <intent-filter>
30        <action android:name="android.intent.action.MAIN" />
31        <category android:name="android.intent.category.LAUNCHER" />
32      </intent-filter>
33
34      <!-- add your deep linking instructions inside the RNBootSplashActivity declaration -->
35      <intent-filter>
36        <action android:name="android.intent.action.VIEW" />
37        <category android:name="android.intent.category.DEFAULT" />
38        <category android:name="android.intent.category.BROWSABLE" />
39        <data android:scheme="YOUR APP SCHEME" /> <!-- replace this with your custom scheme -->
40      </intent-filter>
41    </activity>
42
43    <!-- … -->
44
45  </application>
46
47</manifest>

Testing with Jest

Testing code which uses this library required some setup since we need to mock the native methods.

To add the mocks, create a file jest/setup.js (or any other file name) containing the following code:

1jest.mock("react-native-bootsplash", () => {
2  return {
3    hide: jest.fn().mockResolvedValueOnce(),
4    show: jest.fn().mockResolvedValueOnce(),
5    getVisibilityStatus: jest.fn().mockResolvedValue("hidden"),
6  };
7});

After that, we need to add the setup file in the jest config. You can add it under setupFiles option in your jest config file:

1{
2  "setupFiles": ["<rootDir>/jest/setup.js"]
3}

Using React Navigation

If you are using React Navigation, you can hide the splash screen once the navigation container and all children have finished mounting by using the onReady function.

1import React from "react";
2import { NavigationContainer } from "@react-navigation/native";
3import RNBootSplash from "react-native-bootsplash";
4
5function App() {
6  return (
7    <NavigationContainer onReady={() => RNBootSplash.hide()}>
8      {/* content */}
9    </NavigationContainer>
10  );
11}

🕵️‍♂️ Comparison with react-native-splash-screen

• If react-native-splash-screen encourages you to display an image over your application, react-native-bootsplash way-to-go is to design your launch screen using platforms tools (Xcode layout editor and Android drawable resource).

• It should not prevent you from seeing red screen errors.

• Hiding the launch screen is configurable: fade it out or hide it without any animation at all (no fade needed if you want to animate it out!).