react-native-bootsplash: hiding the native splash when your React Native app is ready

The gap react-native-bootsplash fills between process start and first render

A React Native app does not paint its first frame when the operating system launches the process. The native shell starts, the JavaScript runtime boots, the bundle is evaluated, and only then does React commit a tree. On Android the system shows a window background in the meantime; on iOS it shows a launch storyboard. If you do nothing, users see a flash of white, or a stale image, and then a jump into your UI.

react-native-bootsplash takes over that window. The README describes the package as showing a splash screen during app startup and letting you hide it when ready. That second half is the point. Instead of a fixed timer, your JavaScript decides when the splash goes away, so you can wait for an auth token, a cached session, or a first API response before revealing the app.

The audience is React Native teams shipping to Android and iOS who care about the first two seconds. The repository also lists web in the default platform set of the generator, and the example directory contains a webpack config and a public folder, so a web target is part of the project rather than an afterthought. If your app is JavaScript-only, or you never control the native project, this library is not reachable.

How the generator, the native files and the hide() call fit together

The mechanism has three layers. First, a CLI turns one logo file into platform assets and patches native config: the README says it generates assets, updates config files, and creates the Android Drawable XML file and the iOS Storyboard file. Second, the native side renders that drawable or storyboard as the launch screen, so the image is on screen before any JavaScript runs. Third, the JavaScript module exposes a hide call that tears the native splash down.

The CLI signature is `react-native-bootsplash generate [options] <logo>`, and the argument is a PNG or SVG path. Options include `--platforms` (default `"android,ios,web"`), `--background` (default `"#fff"`), `--logo-width` in dp with a recommended value around 100, `--assets-output` (default `"assets/bootsplash"`), `--flavor` for Android build variants (default `"main"`), and `--html` for the web entry point (default `"public/index.html"`). There is also `--plist` for a custom Info.plist path.

The layout confirms the split: the repository ships `android/`, `ios/`, `src/`, `cli.js`, `app.plugin.js` and `RNBootSplash.podspec` at the top level. The package entry points map to `./dist/commonjs/index.js` and `./dist/module/index.js`, with a separate `./expo` export and an `./app.plugin.js` export. So the same npm package carries a native module, a CLI binary (`"bin": "./cli.js"`), and an Expo config plugin.

One design consequence worth naming: the library does not decide when your app is ready. Nothing in the README describes a timeout or a fallback if you forget to call hide. That responsibility sits entirely with application code.

Installing react-native-bootsplash and generating a first launch screen

Install with npm or yarn. The README warns explicitly to run pod install inside the ios directory afterwards, which is the step people skip when the build then fails.

npm install --save react-native-bootsplash
cd ios && pod install

Before running the generator, inspect its options so you are not guessing at flag names.

npx react-native-bootsplash generate --help

The README shows a full invocation without a license key. Note that `--platforms` takes a comma-separated list and `--background` is hexadecimal without the leading hash in the example.

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

After that, the native launch screen is driven by the generated drawable and storyboard. The remaining work is on the JavaScript side: import the module and call hide when your startup work finishes. The README's core promise is that you hide it when you are ready, so the call belongs after your session restore or first data fetch, not in a module-level statement.

For Expo projects the path is different. The README instructs you to uninstall `expo-splash-screen` and remove its entry from the plugins array, then add the bootsplash plugin to your app config. In a dynamic config the import is `react-native-bootsplash/expo`.

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",
    }),
  ],
});

The README marks the platforms array as required to be explicit, which is easy to miss when converting an existing app.json. Plugin options mirror the CLI: `logo` is required, while `background`, `logoWidth`, `assetsOutput`, `brand`, `brandWidth`, `darkBackground` and the Android `darkContentBarsStyle` flag are optional.

The license key boundary and what the free generator leaves out

This is the trade-off a reader should understand before adopting. The CLI is free to run, but the README states that `--brand`, `--brand-width` and all `--dark-*` options require a `--license-key`. Without one, you get a single logo on a single background per platform.

With a key, the README says the generator can output over fifty files: logo and brand images at every pixel density, dark mode versions, and so on. The license is sold through a Gumroad link, and the README describes it as granting unlimited and unrestricted usage of the generator for the buyer's purposes.

That is a commercial split inside an MIT-licensed package. The library code is MIT, which the LICENSE file and the package.json `"license": "MIT"` field confirm. The asset generator's premium options are a separate product. Nothing in the repository suggests the free path is crippled at runtime; the restriction is on what the generator emits.

If your design has a dark variant, you have three options: buy the key, generate dark assets by hand and wire them into the native projects yourself, or ship a single background that works acceptably in both themes. The third is the cheapest and the most visible compromise. For Expo users there is a fourth detail: the README notes the key can be passed via the `BOOTSPLASH_LICENSE_KEY` environment variable rather than committed into the config.

Where react-native-bootsplash is the wrong tool

The library cannot help you if you never touch native code. It ships `android/`, `ios/` and a podspec, and the README's install instructions end with pod install. Managed workflows that cannot run a native build, or teams that only ever ship over the air, are outside its reach.

It also does not animate. The README's demo assets show a static splash and a GIF, but the CLI options list no animation parameter, and the only motion-related option surface is the logo and brand images. Teams searching for a Lottie-driven splash will not find one here. The generated artifacts are a drawable XML and a storyboard, which are static by nature.

The hide timing is the subtler failure mode. Because the library exposes a hide call and the README describes no timeout, an app that awaits a network request before hiding will hold the splash screen for as long as that request takes. On a slow connection the user stares at a logo with no progress indicator and no way to tell a hang from a load. Any adoption needs a decision about what happens when your startup work never resolves.

Finally, platform coverage is not uniform. The generator defaults to android, ios and web, but the badges in the README name only Android and iOS, and the repository's top-level native directories are `android/` and `ios/`. Treat web as a supported output of the CLI rather than a platform the project advertises equally.

How it differs from expo-splash-screen

The most direct alternative is `expo-splash-screen`, and the README treats it as the thing to remove when adopting bootsplash in an Expo app: uninstall it, then delete its plugin entry, including the `image`, `imageWidth`, `resizeMode` and `backgroundColor` keys.

The difference in approach is where configuration lives. `expo-splash-screen` is configured entirely through the Expo plugin block, with the image and its sizing described as plugin options. react-native-bootsplash keeps a config plugin for Expo, but the same options exist as CLI flags and as native files in the repository, so a bare React Native project uses the identical generator without any Expo dependency.

That matters if you have a bare app, a mixed monorepo, or a web target built with your own webpack config as the example directory suggests. It matters less if you are fully inside Expo and already happy with the plugin block, because switching means removing a dependency and reconfiguring the splash through a different option shape. The migration guide for v6 is referenced at the top of the README, which tells you the maintainers expect version jumps to need reading rather than a lockfile bump.

Maintenance, version support and the upgrade cost

The repository is not archived and the last push was on 2026-09-14, the same day as the 7.3.3 release. The two prior releases landed on 2026-06-19 and 2026-04-08. That is a steady cadence on a small surface area.

The README states the library follows the React Native releases support policy and supports the latest version plus the two previous minor series. That is a narrower window than many packages offer, and it is the main upgrade cost: bumping React Native eventually forces a bootsplash bump too. Because the package ships native code and a podspec, a version bump is not a pure JavaScript change, and the README points v6 users at MIGRATION.md rather than promising a drop-in.

On licensing, the package metadata declares MIT and the repository carries a LICENSE file. The generator's premium options are sold separately through Gumroad under terms the README describes. Whether that matters for your organisation is a question for whoever reviews third-party dependencies; the practical point is that the MIT grant covers the library, not the licensed generator features.

The repository also carries `.github/`, `CODEOWNERS` and an `oxlint.config.ts`, so linting and review ownership are configured in-repo. The example app under `example/` has its own package.json, Gemfile and webpack config, which is where you would look to see a working setup rather than reconstruct one from the README.

Editorial conclusion

Adopt react-native-bootsplash if you ship a bare React Native app on Android and iOS and want the launch screen to stay up until your JS is actually ready, or if you use Expo and are willing to drop expo-splash-screen for the config plugin. Do not adopt it if you need a JavaScript-only solution, if you cannot run a native build, or if you expect the generator to produce dark mode and brand assets without buying a license key. Before committing, verify three things: your React Native version falls inside the supported window (latest plus the two previous minor series), your app runs on all three platforms you list in --platforms, and the hide() call is placed after whatever data your first screen needs, since the library has no built-in timeout.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zoontek/react-native-bootsplash on GitHub