DOCSEARCHbyAlgolia
Submit Docs

react-native-bootsplash

repository·master·Indexed 26 days ago

https://github.com/zoontek/react-native-bootsplash

A library to display a native splash screen during React Native app startup and hide it once the app is ready. It includes a CLI for generating assets for Android, iOS, and Web, an Expo Config Plugin, and a hook for custom hide animations. Version 7.3.2 requires React Native 0.80+, Node.js 20+, and Expo SDK 54+.

Tokens
5K
Snippets
12
Records
27
Agent score
88%

What's inside react-native-bootsplash

  1. Setup with Expo

    master

    To use react-native-bootsplash with Expo:

    1. Uninstall expo-splash-screen from your project.
    2. Add the react-native-bootsplash plugin to your Expo configuration.

    Note: If you have a license key, pass it via the BOOTSPLASH_LICENSE_KEY environment variable.

    Plugin Options:

    • logo (string, required): Logo file path (PNG or SVG).
    • logoWidth (number): Logo width at @1x in dp. Default 100.
    • background (string): Hexadecimal background color. Default #fff.
    • assetsOutput (string): Assets output directory. Default assets/bootsplash.
    • brand (string): Brand file path.
    • brandWidth (number): Brand width at @1x. Default 80.
    • darkBackground (string): Dark mode background color.
    • darkLogo (string): Dark mode logo file path.
    • darkBrand (string): Dark mode brand file path.
    • android.darkContentBarsStyle (boolean): Enforce system bars style.
    // Dynamic configuration (app.config.js or app.config.ts)
import type { ConfigContext, ExpoConfig } from "expo/config";
import bootsplash from "react-native-bootsplash/expo";

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

  2. Enforce system bar colors in Android

    master

    To override the default behavior where system bars use dark-content in light mode and light-content in dark mode, edit your values/styles.xml file to set darkContentBarsStyle within your BootTheme.

    <resources>
  <style name="BootTheme" parent="Theme.BootSplash">
    <item name="darkContentBarsStyle">true</item>
  </style>
</resources>

  3. Setup with bare React Native (iOS)

    master

    For bare React Native projects on iOS, you must initialize the splash screen in your ios/YourApp/AppDelegate.swift file by overriding the customize method.

    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
  }
}

  5. Setup with bare React Native (Android)

    master

    For bare React Native projects on Android, you must initialize the splash screen in your MainActivity.kt file. The implementation varies depending on your react-native-screens version.

    With react-native-screens >= v4.16.0

    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)
    super.onCreate(savedInstanceState)
  }
}

    With react-native-screens < v4.16.0

    import android.os.Bundle
import com.zoontek.rnbootsplash.RNBootSplash

class MainActivity : ReactActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    RNBootSplash.init(this, R.style.BootTheme)
    super.onCreate(null)
  }
}

    Without react-native-screens

    import android.os.Bundle
import com.zoontek.rnbootsplash.RNBootSplash

class MainActivity : ReactActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    RNBootSplash.init(this, R.style.BootTheme)
    super.onCreate(savedInstanceState)
  }
}

  7. Install react-native-bootsplash

    master

    Install the package using npm or yarn. After installation, ensure you run pod install in your ios directory.

    $ npm install --save react-native-bootsplash
# --- or ---
$ yarn add react-native-bootsplash

# IMPORTANT: After installing, run:
$ cd ios && pod install

  8. Mock react-native-bootsplash for Jest tests

    master

    Since react-native-bootsplash relies on native methods, you must mock the module in your Jest setup file to avoid errors during testing.

    // jest/setup.js
jest.mock("react-native-bootsplash", () => {
  return {
    hide: jest.fn().mockResolvedValue(),
    isVisible: jest.fn(),
    useHideAnimation: jest.fn().mockReturnValue({
      container: {},
      logo: { source: 0 },
      brand: { source: 0 },
    }),
  };
});

    Then, ensure this file is included in your Jest configuration:

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

  9. Integrate with React Navigation

    master

    When using React Navigation, it is best practice to hide the splash screen using the onReady callback of the NavigationContainer. This ensures the navigation stack and its children have finished mounting before the splash screen disappears.

    import { NavigationContainer } from "@react-navigation/native";
import BootSplash from "react-native-bootsplash";

const App = () => (
  <NavigationContainer
    onReady={() => {
      BootSplash.hide();
    }}
  >
    {/* content */}
  </NavigationContainer>
);

  10. Configure the Expo plugin for v7

    master

    The Expo plugin configuration has changed. The assetsDir option is renamed to assetsOutput, and the logo path is now a required field. Additionally, the platforms array in app.json must be explicitly defined.

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