🚀 react-native-bootsplash

Show a splash screen during app startup. Hide it when you are ready. For migration from the v6, 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

$ 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.

Setup

Assets generation

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

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

The command can take multiple arguments:

Usage: react-native-bootsplash generate [options] <logo>

Generate a launch screen using a logo file path (PNG or SVG)

Arguments:
  logo                        Logo file path (PNG or SVG)

Options:
  --platforms <list>          Platforms to generate for, separated by a comma (default: "android,ios,web")
  --background <string>       Background color (in hexadecimal format) (default: "#fff")
  --logo-width <number>       Logo width at @1x (in dp - we recommend approximately ~100) (default: 100)
  --assets-output <string>    Assets output directory path (default: "assets/bootsplash")
  --flavor <string>           Android flavor build variant (where your resource directory is) (default: "main")
  --html <string>             HTML template file path (your web app entry point) (default: "public/index.html")
  --plist <string>            Custom Info.plist file path
  --license-key <string>      License key to enable brand and dark mode assets generation
  --brand <string>            Brand file path (PNG or SVG)
  --brand-width <number>      Brand width at @1x (in dp - we recommend approximately ~80) (default: 80)
  --dark-background <string>  [dark mode] Background color (in hexadecimal format)
  --dark-logo <string>        [dark mode] Logo file path (PNG or SVG)
  --dark-brand <string>       [dark mode] Brand file path (PNG or SVG)
  -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

# Without license key
yarn react-native-bootsplash generate svgs/light-logo.svg \
  --platforms=android,ios,web \
  --background=F5FCFF \
  --logo-width=100 \
  --assets-output=assets/bootsplash \
  --flavor=main \
  --html=public/index.html

# With license key 🔑
yarn react-native-bootsplash generate svgs/light-logo.svg \
  --platforms=android,ios,web \
  --background=F5FCFF \
  --logo-width=100 \
  --assets-output=assets/bootsplash \
  --flavor=main \
  --html=public/index.html \
  --license-key=xxxxx \
  --brand=svgs/light-brand.svg \
  --brand-width=80 \
  --dark-background=00090A \
  --dark-logo=svgs/dark-logo.svg \
  --dark-brand=svgs/dark-brand.svg

With Expo

1. First, uninstall expo-splash-screen:

$ npm uninstall expo-splash-screen
# --- or ---
$ yarn remove expo-splash-screen

{
  "expo": {
    "plugins": [
-     [
-       "expo-splash-screen",
-       {
-         "image": "./assets/images/splash-icon.png",
-         "imageWidth": 200,
-         "resizeMode": "contain",
-         "backgroundColor": "#ffffff"
-       }
-     ],
    ]
  }
}

2. Add the plugin in your app config (if you have a license key, pass it via the BOOTSPLASH_LICENSE_KEY environment variable):

import type { ConfigContext, ExpoConfig } from "expo/config";
import bootsplash from "react-native-bootsplash/expo"; // use `require` in app.config.js

export default ({ config }: ConfigContext): ExpoConfig => ({
  // …
  platforms: ["android", "ios", "web"], // must be explicit
  plugins: [
    bootsplash({
      logo: "./assets/logo.png",
      logoWidth: 100,
      background: "#f5fcff",
      // …
    }),
  ],
});

{
  "expo": {
    // …
    "platforms": ["android", "ios", "web"], // must be explicit
    "plugins": [
      [
        "react-native-bootsplash",
        {
          "logo": "./assets/logo.png",
          "logoWidth": 100,
          "background": "#f5fcff",
          // …
        },
      ],
    ],
  },
}

📌 The available plugins options are:

type PluginOptions = {
  android?: {
    darkContentBarsStyle?: boolean; // Enforce system bars style (default: undefined)
  };

  logo: string; // Logo file path (PNG or SVG) - required
  background?: string; // Background color (in hexadecimal format) (default: "#fff")
  logoWidth?: number; // Logo width at @1x (in dp - we recommend approximately ~100) (default: 100)
  assetsOutput?: string; // Assets output directory path (default: "assets/bootsplash")

  // Addon options
  brand?: string; // Brand file path (PNG or SVG)
  brandWidth?: number; // Brand width at @1x (in dp - we recommend approximately ~80) (default: 80)
  darkBackground?: string; // [dark mode] Background color (in hexadecimal format)
  darkLogo?: string; // [dark mode] Logo file path (PNG or SVG)
  darkBrand?: string; // [dark mode] Brand file path (PNG or SVG)
};

With bare React Native

iOS

Edit your ios/YourApp/AppDelegate.swift file:

import ReactAppDependencyProvider
import RNBootSplash // ⬅️ add this import

// …

class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {

  // …

  // ⬇️ override this method
  override func customize(_ rootView: RCTRootView) {
    super.customize(rootView)
    RNBootSplash.initWithStoryboard("BootSplash", rootView: rootView) // ⬅️ initialize the splash screen
  }
}

Android

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

// ⬇️ add these required imports
import android.os.Bundle
import com.zoontek.rnbootsplash.RNBootSplash

// …

class MainActivity : ReactActivity() {

  // …

  override fun onCreate(savedInstanceState: Bundle?) {
    RNBootSplash.init(this, R.style.BootTheme) // ⬅️ initialize the splash screen
    super.onCreate(savedInstanceState)
  }
}

// ⬇️ add these required imports
import android.os.Bundle
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory
import com.zoontek.rnbootsplash.RNBootSplash

// …

class MainActivity : ReactActivity() {

  // …

  override fun onCreate(savedInstanceState: Bundle?) {
    supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
    RNBootSplash.init(this, R.style.BootTheme) // ⬅️ initialize the splash screen
    super.onCreate(savedInstanceState)
  }
}

// ⬇️ add these required imports
import android.os.Bundle
import com.zoontek.rnbootsplash.RNBootSplash

// …

class MainActivity : ReactActivity() {

  // …

  override fun onCreate(savedInstanceState: Bundle?) {
    RNBootSplash.init(this, R.style.BootTheme) // ⬅️ initialize the splash screen
    super.onCreate(null)
  }
}

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

API

hide()

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

Method type

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

Usage

import { useEffect } from "react";
import { Text } from "react-native";
import BootSplash from "react-native-bootsplash";

const App = () => {
  useEffect(() => {
    const init = async () => {
      // …do multiple sync or async tasks
    };

    init().finally(async () => {
      await BootSplash.hide({ fade: true });
      console.log("BootSplash has been hidden successfully");
    });
  }, []);

  return <Text>My awesome app</Text>;
};

isVisible()

Return the current visibility status of the native splash screen.

Method type

type isVisible = () => boolean;

Usage

import BootSplash from "react-native-bootsplash";

if (BootSplash.isVisible()) {
  // Do something
}

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

type useHideAnimation = (config: {
  ready?: boolean; // a boolean flag to delay the animate execution (default: true)

  // the required generated assets
  manifest: Manifest; // the manifest file is generated in your assets directory
  logo?: ImageRequireSource;
  darkLogo?: ImageRequireSource;
  brand?: ImageRequireSource;
  darkBrand?: ImageRequireSource;

  // specify if you are using translucent status / navigation bars
  // in order to avoid a shift between the native and JS splash screen
  statusBarTranslucent?: boolean;
  navigationBarTranslucent?: boolean;

  animate: () => void;
}) => {
  container: ContainerProps;
  logo: LogoProps;
  brand: BrandProps;
};

Usage

import { useState } from "react";
import { Animated, Image } from "react-native";
import BootSplash from "react-native-bootsplash";

type Props = {
  onAnimationEnd: () => void;
};

const AnimatedBootSplash = ({ onAnimationEnd }: Props) => {
  const [opacity] = useState(() => new Animated.Value(1));

  const { container, logo /*, brand */ } = BootSplash.useHideAnimation({
    manifest: require("../assets/bootsplash/manifest.json"),

    logo: require("../assets/bootsplash/logo.png"),
    // darkLogo: require("../assets/bootsplash/dark-logo.png"),
    // brand: require("../assets/bootsplash/brand.png"),
    // darkBrand: require("../assets/bootsplash/dark-brand.png"),

    animate: () => {
      // Perform animations and call onAni