react-native-bootsplash
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.2 • Public • Published

    🚀 react-native-bootsplash

    This library helped you? Consider sponsoring!

    Show a bootsplash during app startup. Hide it when you are ready.
    For migration from the v3, check the MIGRATION.md guide.

    npm version npm MIT Platform - Android Platform - iOS

    iOS demo android demo

    Support

    version react-native version
    4.0.0+ 0.65.0+
    3.0.0+ 0.63.0+

    Installation

    $ npm install --save react-native-bootsplash
    # --- or ---
    $ 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.65.0+, you probably don't need to link it manually. But if you have a special case, follow these additional instructions:

    👀 See manual linking instructions

    iOS

    Add this line to your ios/Podfile file, then run pod install.

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

    Android

    1. Add the following lines to android/settings.gradle:
    include ':react-native-bootsplash'
    project(':react-native-bootsplash').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-bootsplash/android')
    1. Add the implementation line to the dependencies in android/app/build.gradle:
    dependencies {
      // ...
      implementation project(':react-native-bootsplash')
    }
    1. Add the import and link the package in MainApplication.java:
    import com.zoontek.rnbootsplash.RNBootSplashPackage; // <- add the RNBootSplashPackage import
    
    public class MainApplication extends Application implements ReactApplication {
    
      //
    
      @Override
      protected List<ReactPackage> getPackages() {
        @SuppressWarnings("UnnecessaryLocalVariable")
        List<ReactPackage> packages = new PackageList(this).getPackages();
        //
        packages.add(new RNBootSplashPackage());
        return packages;
      }
    
      //
    }

    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 .

    $ npx react-native generate-bootsplash --help
    # --- or ---
    $ yarn react-native generate-bootsplash --help

    The command can take multiple arguments:

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

    Full command usage example

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

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

    # Only if --assets-path was specified
    assets/bootsplash_logo.png
    assets/bootsplash_logo@1,5x.png
    assets/bootsplash_logo@2x.png
    assets/bootsplash_logo@3x.png
    assets/bootsplash_logo@4x.png
    
    android/app/src/main/res/values/colors.xml (creation and edition)
    android/app/src/main/res/mipmap-hdpi/bootsplash_logo.png
    android/app/src/main/res/mipmap-mdpi/bootsplash_logo.png
    android/app/src/main/res/mipmap-xhdpi/bootsplash_logo.png
    android/app/src/main/res/mipmap-xxhdpi/bootsplash_logo.png
    android/app/src/main/res/mipmap-xxxhdpi/bootsplash_logo.png
    
    ios/YourProjectName/BootSplash.storyboard
    ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo.png
    ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo@2x.png
    ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/bootsplash_logo@3x.png

    iOS

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

    Edit the ios/YourProjectName/AppDelegate.m file:

    #import "AppDelegate.h"
    
    #import <React/RCTBridge.h>
    #import <React/RCTBundleURLProvider.h>
    #import <React/RCTRootView.h>
    
    #import "RNBootSplash.h" // <- add the header import
    
    @implementation AppDelegate
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      //
      rootViewController.view = rootView;
      self.window.rootViewController = rootViewController;
      [self.window makeKeyAndVisible];
    
      [RNBootSplash initWithStoryboard:@"BootSplash" rootView:rootView]; // <- initialization using the storyboard file name
    
      return YES;
    }

    Set the BootSplash.storyboard as launch screen file:

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

    Android

    1. As this library only support Android 6+, you probably have to edit your android/build.gradle file:
    buildscript {
      ext {
        buildToolsVersion = "30.0.2"
        minSdkVersion = 23 // <- AndroidX splashscreen has basic support for 21 (only the background color), so 23 is best
        compileSdkVersion = 31 // <- set at least 31
        targetSdkVersion = 31 // <- set at least 31
    
        //
    1. Then edit your android/app/build.gradle file:
    dependencies {
      implementation fileTree(dir: "libs", include: ["*.jar"])
      //noinspection GradleDynamicVersion
      implementation "com.facebook.react:react-native:+"  // From node_modules
    
      implementation "androidx.core:core-splashscreen:1.0.0-alpha02" // Add this line
    
      //
    1. Edit your android/app/src/main/res/values/styles.xml file:
    <resources>
    
      <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
          <!-- Your base theme customization -->
      </style>
    
      <!-- BootTheme should inherit from Theme.SplashScreen -->
      <style name="BootTheme" parent="Theme.SplashScreen">
        <item name="windowSplashScreenBackground">@color/bootsplash_background</item>
        <item name="windowSplashScreenAnimatedIcon">@mipmap/bootsplash_logo</item>
        <item name="postSplashScreenTheme">@style/AppTheme</item>
      </style>
    
    </resources>
    1. Edit your android/app/src/main/AndroidManifest.xml file:
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.rnbootsplashexample">
    
      <!---->
    
      <application
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:allowBackup="false"
        android:theme="@style/BootTheme"> <!-- Replace @style/AppTheme with @style/BootTheme -->
        <activity
        android:name=".MainActivity"
        android:label="@string/app_name"
        android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
        android:launchMode="singleTask"
        android:windowSoftInputMode="adjustResize"
        android:exported="true"> <!-- Add android:exported="true" -->
        <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        </activity>
      </application>
    </manifest>
    
    1. Finally edit your android/app/src/main/java/com/yourprojectname/MainActivity.java file:
    import com.facebook.react.ReactActivity;
    import com.facebook.react.ReactActivityDelegate; // <- add this necessary import
    import com.zoontek.rnbootsplash.RNBootSplash; // <- add this necessary import
    
    public class MainActivity extends ReactActivity {
    
      //
    
      @Override
      protected ReactActivityDelegate createReactActivityDelegate() {
        return new ReactActivityDelegate(this, getMainComponentName()) {
    
          @Override
          protected void loadApp(String appKey) {
            RNBootSplash.init(MainActivity.this); // <- initialize the splash screen
            super.loadApp(appKey);
          }
        };
      }
    }

    API

    hide()

    Method type

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

    Usage

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

    getVisibilityStatus()

    Method type

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

    Usage

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

    Real world example

    import React, { useEffect } from "react";
    import { Text } from "react-native";
    import RNBootSplash from "react-native-bootsplash";
    
    function App() {
      useEffect(() => {
        const init = async () => {
          // …do multiple sync or async tasks
        };
    
        init().finally(async () => {
          await RNBootSplash.hide({ fade: true });
          console.log("Bootsplash has been hidden successfully");
        });
      }, []);
    
      return <Text>My awesome app</Text>;
    }

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

    Testing with Jest

    Testing code which uses this library requires 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:

    jest.mock("react-native-bootsplash", () => {
      return {
        show: jest.fn().mockResolvedValueOnce(),
        getVisibilityStatus: jest.fn().mockResolvedValue("hidden"),
      };
    });

    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:

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

    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.

    import React from "react";
    import { NavigationContainer } from "@react-navigation/native";
    import RNBootSplash from "react-native-bootsplash";
    
    function App() {
      return (
        <NavigationContainer onReady={() => RNBootSplash.hide()}>
          {/* content */}
        </NavigationContainer>
      );
    }

    🕵️‍♂️ 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.
    • 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.

    Install

    npm i react-native-bootsplash

    DownloadsWeekly Downloads

    45,721

    Version

    4.0.2

    License

    MIT

    Unpacked Size

    130 kB

    Total Files

    30

    Last publish

    Collaborators

    • zoontek