Show a bootsplash during app startup. Hide it when you are ready.
For the stable version, check the 3.2.6
tag README.md
.
For migration from the v3, check the MIGRATION.md
file.
version | react-native version |
---|---|
4.0.0+ | 0.65.0+ |
3.0.0+ | 0.63.0+ |
$ npm install --save react-native-bootsplash@next
# --- or ---
$ yarn add react-native-bootsplash@next
Don't forget going into the ios
directory to execute a pod install
.
npm link react-native-bootsplash
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
Add this line to your ios/Podfile
file, then run pod install
.
target 'YourAwesomeProject' do
# …
pod 'RNBootSplash', :path => '../node_modules/react-native-bootsplash'
end
- 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')
- Add the implementation line to the dependencies in
android/app/build.gradle
:
dependencies {
// ...
implementation project(':react-native-bootsplash')
}
- 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;
}
// …
}
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:
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
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:
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
# 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
.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 |
---|---|---|
- 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
// …
- 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
// …
- 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>
- 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>
- 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);
}
};
}
}
type hide = (config?: { fade?: boolean }) => Promise<void>;
import RNBootSplash from "react-native-bootsplash";
RNBootSplash.hide(); // immediate
RNBootSplash.hide({ fade: true }); // fade
type VisibilityStatus = "visible" | "hidden" | "transitioning";
type getVisibilityStatus = () => Promise<VisibilityStatus>;
import RNBootSplash from "react-native-bootsplash";
RNBootSplash.getVisibilityStatus().then((status) => console.log(status));
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 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"]
}
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 at all (no fade needed if you want to animate it out!).