🚀 react-native-bootsplash

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

Support

This library follows the React Native releases support policy.
It is supporting the latest version, and the two previous minor series.

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.

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-bootsplash generate --help
2# --- or ---
3$ yarn react-native-bootsplash generate --help

The command can take multiple arguments:

1Usage: react-native-bootsplash generate [options] <logo>
2
3Generate a launch screen using a logo file path (PNG or SVG)
4
5Options:
6  --project-type <string>     Project type ("detect", "bare" or "expo") (default: "detect")
7  --platforms <list>          Platforms to generate for, separated by a comma (default: "android,ios,web")
8  --background <string>       Background color (in hexadecimal format) (default: "#fff")
9  --logo-width <number>       Logo width at @1x (in dp - we recommend approximately ~100) (default: 100)
10  --assets-output <string>    Assets output directory path (default: "assets/bootsplash")
11  --flavor <string>           Android flavor build variant (where your resource directory is) (default: "main")
12  --html <string>             HTML template file path (your web app entry point) (default: "public/index.html")
13  --license-key <string>      License key to enable brand and dark mode assets generation
14  --brand <string>            Brand file path (PNG or SVG)
15  --brand-width <number>      Brand width at @1x (in dp - we recommend approximately ~80) (default: 80)
16  --dark-background <string>  [dark mode] Background color (in hexadecimal format)
17  --dark-logo <string>        [dark mode] Logo file path (PNG or SVG)
18  --dark-brand <string>       [dark mode] Brand file path (PNG or SVG)
19  -h, --help                  display help for command

💪 Unlock the CLI full potential

In order to use the --brand, --brand-width and --dark-* options, you must specify a --license-key.

With it, the generator is able to output over 50 files (logo and brand images generated in all pixel densities, dark mode versions, etc.), saving you (and your company!) a massive amount of time not only at creation, but also at each adjustment ⏱️

📍 This license key grants unlimited and unrestricted usage of the generator for the buyer's purposes (meaning you can execute the assets generation as much as you want).

Full command usage example

1# Without license key
2yarn react-native-bootsplash generate svgs/light-logo.svg \
3  --platforms=android,ios,web \
4  --background=F5FCFF \
5  --logo-width=100 \
6  --assets-output=assets/bootsplash \
7  --flavor=main \
8  --html=public/index.html
9
10# With license key 🔑
11yarn react-native-bootsplash generate svgs/light-logo.svg \
12  --platforms=android,ios,web \
13  --background=F5FCFF \
14  --logo-width=100 \
15  --assets-output=assets/bootsplash \
16  --flavor=main \
17  --html=public/index.html \
18  --license-key=xxxxx \
19  --brand=svgs/light-brand.svg \
20  --brand-width=80 \
21  --dark-background=00090A \
22  --dark-logo=svgs/dark-logo.svg \
23  --dark-brand=svgs/dark-brand.svg

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

1# Without license key
2android/app/src/main/res/drawable-mdpi/bootsplash_logo.png
3android/app/src/main/res/drawable-hdpi/bootsplash_logo.png
4android/app/src/main/res/drawable-xhdpi/bootsplash_logo.png
5android/app/src/main/res/drawable-xxhdpi/bootsplash_logo.png
6android/app/src/main/res/drawable-xxxhdpi/bootsplash_logo.png
7android/app/src/main/AndroidManifest.xml
8android/app/src/main/res/values/colors.xml
9android/app/src/main/res/values/styles.xml
10
11ios/YourApp/BootSplash.storyboard
12ios/YourApp/Colors.xcassets/BootSplashBackground-<hash>.colorset/Contents.json
13ios/YourApp/Images.xcassets/BootSplashLogo-<hash>.imageset/Contents.json
14ios/YourApp/Images.xcassets/BootSplashLogo-<hash>.imageset/logo-<hash>.png
15ios/YourApp/Images.xcassets/BootSplashLogo-<hash>.imageset/logo-<hash>@2x.png
16ios/YourApp/Images.xcassets/BootSplashLogo-<hash>.imageset/logo-<hash>@3x.png
17ios/YourApp/Info.plist
18ios/YourApp.xcodeproj/project.pbxproj
19
20public/index.html
21
22assets/bootsplash/manifest.json
23assets/bootsplash/logo.png
24assets/bootsplash/logo@1,5x.png
25assets/bootsplash/logo@2x.png
26assets/bootsplash/logo@3x.png
27assets/bootsplash/logo@4x.png
28
29# + Over 40 files with license key 🔑 (brand images, dark mode versions…)

With Expo

1. First, uninstall expo-splash-screen:

1$ npm uninstall expo-splash-screen
2# --- or ---
3$ yarn remove expo-splash-screen

2. Add the plugin in your app.json:

1{
2  "expo": {
3    "plugins": [
4-     [
5-       "expo-splash-screen",
6-       {
7-         "image": "./assets/images/splash-icon.png",
8-         "imageWidth": 200,
9-         "resizeMode": "contain",
10-         "backgroundColor": "#ffffff"
11-       }
12-     ],
13+     ["react-native-bootsplash", { "assetsDir": "assets/bootsplash" }]
14    ]
15  }
16}

📌 The available plugins options are:

1type PluginOptions = {
2  assetsDir?: string; // optional, default is "assets/bootsplash"
3  android?: {
4    parentTheme?: "TransparentStatus" | "EdgeToEdge"; // optional, default is `undefined` (`Theme.BootSplash`)
5    darkContentBarsStyle?: boolean; // optional, default is `undefined`
6  };
7};

With bare React Native

iOS (react-native 0.79+)

Edit your ios/YourApp/AppDelegate.swift file:

1import ReactAppDependencyProvider
2import RNBootSplash // ⬅️ add this import
3
4// …
5
6class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
7
8  // …
9
10  // ⬇️ override this method
11  override func customize(_ rootView: RCTRootView) {
12    super.customize(rootView)
13    RNBootSplash.initWithStoryboard("BootSplash", rootView: rootView) // ⬅️ initialize the splash screen
14  }
15}

iOS (react-native 0.77+)

Edit your ios/YourApp/AppDelegate.swift file:

1import ReactAppDependencyProvider
2import RNBootSplash // ⬅️ add this import
3
4// …
5
6@main
7class AppDelegate: RCTAppDelegate {
8
9  // …
10
11  // ⬇️ override this method
12  override func customize(_ rootView: RCTRootView!) {
13    super.customize(rootView)
14    RNBootSplash.initWithStoryboard("BootSplash", rootView: rootView) // ⬅️ initialize the splash screen
15  }
16}

Android

Edit your android/app/src/main/java/com/yourapp/MainActivity.kt file:

1// ⬇️ add these required imports
2import android.os.Bundle
3import com.zoontek.rnbootsplash.RNBootSplash
4
5// …
6
7class MainActivity : ReactActivity() {
8
9  // …
10
11  override fun onCreate(savedInstanceState: Bundle?) {
12    RNBootSplash.init(this, R.style.BootTheme) // ⬅️ initialize the splash screen
13    super.onCreate(savedInstanceState) // super.onCreate(null) with react-native-screens
14  }
15}

ℹ️ Refer to previous package documentation for setup steps with React Native < 0.77.

API

hide()

Hide the splash screen (immediately, or with a fade out).

Method type

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

Usage

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

isVisible()

Return the current visibility status of the native splash screen.

Method type

1type isVisible = () => Promise<boolean>;

Usage

1import BootSplash from "react-native-bootsplash";
2
3BootSplash.isVisible().then((value) => console.log(value));

useHideAnimation()

A hook to easily create a custom hide animation by animating all splash screen elements using Animated, react-native-reanimated or else (similar as the video on top of this documentation).

Method type

1type useHideAnimation = (config: {
2  ready?: boolean; // a boolean flag to delay the animate execution (default: true)
3
4  // the required generated assets
5  manifest: Manifest; // the manifest file is generated in your assets directory
6  logo?: ImageRequireSource;
7  darkLogo?: ImageRequireSource;
8  brand?: ImageRequireSource;
9  darkBrand?: ImageRequireSource;
10
11  // specify if you are using translucent status / navigation bars
12  // in order to avoid a shift between the native and JS splash screen
13  statusBarTranslucent?: boolean;
14  navigationBarTranslucent?: boolean;
15
16  animate: () => void;
17}) => {
18  container: ContainerProps;
19  logo: LogoProps;
20  brand: BrandProps;
21};

Usage

1import { useState } from "react";
2import { Animated, Image } from "react-native";
3import BootSplash from "react-native-bootsplash";
4
5type Props = {
6  onAnimationEnd: () => void;
7};
8
9const AnimatedBootSplash = ({ onAnimationEnd }: Props) => {
10  const [opacity] = useState(() => new Animated.Value(1));
11
12  const { container, logo /*, brand */ } = BootSplash.useHideAnimation({
13    manifest: require("../assets/bootsplash/manifest.json"),
14
15    logo: require("../assets/bootsplash/logo.png"),
16    // darkLogo: require("../assets/bootsplash/dark-logo.png"),
17    // brand: require("../assets/bootsplash/brand.png"),
18    // darkBrand: require("../assets/bootsplash/dark-brand.png"),
19
20    statusBarTranslucent: true,
21    navigationBarTranslucent: false,
22
23    animate: () => {
24      // Perform animations and call onAnimationEnd
25      Animated.timing(opacity, {
26        useNativeDriver: true,
27        toValue: 0,
28        duration: 500,
29      }).start(() => {
30        onAnimationEnd();
31      });
32    },
33  });
34
35  return (
36    <Animated.View {...container} style={[container.style, { opacity }]}>
37      <Image {...logo} />
38      {/* <Image {...brand} /> */}
39    </Animated.View>
40  );
41};
42
43const App = () => {
44  const [visible, setVisible] = useState(true);
45
46  return (
47    <View style={{ flex: 1 }}>
48      {/* content */}
49
50      {visible && (
51        <AnimatedBootSplash
52          onAnimationEnd={() => {
53            setVisible(false);
54          }}
55        />
56      )}
57    </View>
58  );
59};

This example is simple for documentation purpose (we only animate the container).
🤙 A more complex example is available in the /example folder.

FAQ

How can I have a transparent status bar, or edge-to-edge layout?

Edit your values/styles.xml file to inherit from Theme.BootSplash.TransparentStatus / Theme.BootSplash.EdgeToEdge instead of Theme.BootSplash:

1<resources>
2
3  <!-- … -->
4
5  <!-- make BootTheme inherit from Theme.BootSplash.TransparentStatus / Theme.BootSplash.EdgeToEdge -->
6  <style name="BootTheme" parent="Theme.BootSplash.EdgeToEdge">
7    <!-- … -->
8
9    <!-- optional, used to enforce the initial bars styles -->
10    <!-- default is true in light mode, false in dark mode -->
11    <item name="darkContentBarsStyle">true</item>
12  </style>
13
14</resources>

Why are both light and dark assets inlined in my index.html?

For the sake of simplicity. Since the light and dark versions of your assets are likely identical (except for the colors), if your index.html file is compressed with gzip, the size difference will be negligible.

How should I use it with 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 { NavigationContainer } from "@react-navigation/native";
2import BootSplash from "react-native-bootsplash";
3
4const App = () => (
5  <NavigationContainer
6    onReady={() => {
7      BootSplash.hide();
8    }}
9  >
10    {/* content */}
11  </NavigationContainer>
12);

How can I mock the module in my tests?

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:

1jest.mock("react-native-bootsplash", () => {
2  return {
3    hide: jest.fn().mockResolvedValue(),
4    isVisible: jest.fn().mockResolvedValue(false),
5    useHideAnimation: jest.fn().mockReturnValue({
6      container: {},
7      logo: { source: 0 },
8      brand: { source: 0 },
9    }),
10  };
11});

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}

Sponsors

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.