Show a splash screen during app startup. Hide it when you are ready.
For migration from the v3, check the MIGRATION.md
guide.
version | react-native version |
---|---|
4.0.0+ | 0.65.0+ |
3.0.0+ | 0.63.0+ |
$ npm install --save react-native-bootsplash
# --- or ---
$ yarn add react-native-bootsplash
ios
directory to execute a pod install
.
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:
yarn react-native generate-bootsplash <logoPath>
Generate a launch screen using an original logo file (PNG or SVG)
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")
--platforms <platforms> platforms to generate assets for (comma separated) (default: "android,ios")
-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 \
--platforms=android,ios
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/[email protected]
assets/[email protected]
assets/[email protected]
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/[email protected]
ios/YourProjectName/Images.xcassets/BootSplashLogo.imageset/[email protected]
ℹ️ For react-native
< 0.71
setup, follow the v4.4.0 README.md
.
Edit the ios/YourProjectName/AppDelegate.mm
file:
#import "AppDelegate.h"
#import "RNBootSplash.h" // ⬅️ add the header import
// …
@implementation AppDelegate
// …
// ⬇️ Add this before file @end
- (UIView *)createRootViewWithBridge:(RCTBridge *)bridge
moduleName:(NSString *)moduleName
initProps:(NSDictionary *)initProps {
UIView *rootView = [super createRootViewWithBridge:bridge
moduleName:moduleName
initProps:initProps];
[RNBootSplash initWithStoryboard:@"BootSplash" rootView:rootView]; // ⬅️ initialize the splash screen
return rootView;
}
@end
Set the BootSplash.storyboard
as launch screen file:
Drag and drop the file | Create folder reference | Set as Launch Screen File |
---|---|---|
![]() |
![]() |
![]() |
- Edit your
android/app/build.gradle
file:
dependencies {
// …
implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.0.0")
implementation("androidx.core:core-splashscreen:1.0.0") // add this line
// …
android
directory to execute a ./gradlew clean && ./gradlew build
(or perform a Gradle sync in Android Studio).
- 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="https://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 -->
<!-- … -->
</application>
</manifest>
- Finally edit your
android/app/src/main/java/com/yourprojectname/MainActivity.java
file:
// …
// add these required imports:
import android.os.Bundle;
import com.zoontek.rnbootsplash.RNBootSplash;
public class MainActivity extends ReactActivity {
// …
@Override
protected void onCreate(Bundle savedInstanceState) {
RNBootSplash.init(this); // ⬅️ initialize the splash screen
super.onCreate(savedInstanceState); // or super.onCreate(null) with react-native-screens
}
}
type hide = (config?: { fade?: boolean; duration?: number }) => Promise<void>;
Note: Only durations above 220ms are visually noticeable. Smaller values will be ignored and the default duration will be used.
import RNBootSplash from "react-native-bootsplash";
RNBootSplash.hide(); // immediate
RNBootSplash.hide({ fade: true }); // fade with 220ms default duration
RNBootSplash.hide({ fade: true, duration: 500 }); // fade with custom duration
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, duration: 500 });
console.log("BootSplash has been hidden successfully");
});
}, []);
return <Text>My awesome app</Text>;
}
🤙 A more complex example is available in the /example
folder.
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>
);
}
In order to keep fully transparent status and navigation bars on Android once the splash screen is hidden (and control them), this library play nicely with react-native-bars. Check its README for more informations.
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 {
hide: 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"]
}
This module is provided as is, I work on it in my free time.
If you or your company uses it in a production app, consider sponsoring this project 💰. You also can contact me for premium enterprise support: help with issues, prioritize bugfixes, feature requests, etc.