npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-native-splash-motion

v0.1.4

Published

React Native splash screen with animated Lottie & dotLottie, rendered natively before your JS loads. Expo + bare React Native, zero native code, built on Nitro Modules.

Readme

react-native-splash-motion

npm version CI License: MIT

An animated React Native splash screen with Lottie & dotLottie — rendered natively, before your JavaScript loads.

Most "animated splash" solutions render the animation with React, so it can only start once the JS bundle has loaded. Until then your users stare at a static image. SplashMotion plays your animation in a native view from the very first frames of app launch, keeps it running while the bundle loads, and hands off to your app with a polished outro.

  • 🎬 Lottie or dotLottie — bring the file your designer exported (.json or .lottie)
  • ⚡ Native from frame one — Core Animation on iOS, off-main-thread rendering on Android
  • 🪄 Zero native code — no AppDelegate / MainActivity edits, it wires itself up
  • 🧩 Expo & bare React Native — config plugin + CLI share the same generator
  • 🔥 New Architecture only, built on Nitro Modules
  • 🎯 Smart exit — finishes the current loop, plays your outro, then fades

Demo

What you're seeing, from the tap on the app icon:

  1. The OS launch screen shows your background color straight away, before any of your code runs.
  2. The animation plays natively while React Native starts and your JavaScript loads in the background.
  3. Your app calls hide() once it's ready. The current loop finishes, then the splash fades out to reveal the app.

Both recordings are release builds of the example app, with the splash generated by:

npx splash-motion generate assets/splash.json --background "#0F6E56" --width 160

How it compares

| | SplashMotion | expo-splash-screen | react-native-bootsplash | | --------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | Native Lottie / dotLottie animation before and during JS loading | ✅ | ❌ (static image) | ❌ (static image) | | Native loop/outro markers and automatic exit sequence | ✅ | ❌ | ❌ | | Expo config plugin | ✅ | ✅ | ✅ | | Bare React Native setup | CLI; no native edits | Manual native configuration | Asset CLI + native code edits | | Old Architecture support | ❌ | ✅ | ✅ |

Requirements

  • React Native with the New Architecture enabled (the default since 0.76)
  • react-native-nitro-modules
  • iOS 15+ · Android 7+ (API 24)
  • Expo: a development build (Expo Go can't load custom native code)

Installation

yarn add react-native-splash-motion react-native-nitro-modules

Your animation file

Put the file anywhere in your project (e.g. assets/splash.json) and point the CLI or Expo plugin at it. The format is picked from the extension:

| Format | Extension | Where it comes from | | --------- | --------- | ------------------------------------------------------------------- | | Lottie | .json | After Effects + Bodymovin, or "Lottie JSON" download on LottieFiles | | dotLottie | .lottie | "dotLottie" download on LottieFiles, or any dotLottie v1/v2 export |

  • .lottie files are unpacked at build time into plain Lottie JSON. Images bundled inside are embedded, so they render as-is. If the file contains several animations, the active one (or the first) is used.
  • The animation is copied into the native project when you run the generator, so after replacing the file, run it again and rebuild.

See Designing your animation for markers (loop, outro) and other tips.

Size

The animation is drawn at a fixed size, centered on the splash background. Sizes are in points on iOS and dp on Android.

| Option | Default | | ---------- | --------------------------------------------------------- | | --width | 160 | | --height | Follows the animation's own aspect ratio (its w / h). |

Both must be positive numbers; decimals are fine. There is no upper limit, but at runtime the animation is scaled down to fit 90% of the screen's width and height, keeping its aspect ratio, so a large value never gets cut off (on phones, in landscape or in split-screen). It is never scaled up, so on tablets it stays at the size you set. The iOS launch-screen --still image follows the same rule, so the hand-off doesn't jump.

First frame on the launch screen (--still)

Before your app's process is running, no code can play an animation: iOS shows its launch storyboard and Android its system splash, both static. Without a still, that moment shows only the background color. Pass a PNG of your animation's first frame (transparent background, ideally at 3× or 4× the size you set) and the CLI puts it on both launch screens at exactly the place and size of the animation, so the animation looks like it is there from the first tap and simply starts moving:

npx splash-motion generate assets/splash.json --background "#0F6E56" --still assets/splash-first-frame.png

Export the frame from After Effects or LottieFiles. With --loop-marker, use the first frame of that marker instead, since that's where playback starts. Automatic extraction (no PNG needed) is on the roadmap; for now the PNG has to come from you.

On Android the system splash only shows a centered circle 192dp wide, so keep the first frame's artwork inside that circle (or use a width of about 135dp or less to show all of it). Anything outside it appears as soon as the animation takes over.

Bare React Native

Generate the splash from your animation, then rebuild:

npx splash-motion generate assets/splash.json --background "#0F6E56"
cd ios && pod install

That's it — there is no native code to add. SplashMotion replaces your launch storyboard (LaunchScreen.storyboard in a bare project, SplashScreen.storyboard in Expo). If the current one wasn't generated by SplashMotion, it's kept next to it as <name>.storyboard.bak first; later runs only touch the file SplashMotion generated.

Expo

Remove expo-splash-screen (SplashMotion replaces it), then add the plugin:

{
  "expo": {
    "plugins": [
      [
        "react-native-splash-motion",
        {
          "source": "./assets/splash.json",
          "background": "#0F6E56",
          "width": 200
        }
      ]
    ]
  }
}
npx expo prebuild --clean

Usage

Hide the splash once your app is ready:

import SplashMotion from 'react-native-splash-motion';

<NavigationContainer onReady={() => SplashMotion.hide()}>
  {/* … */}
</NavigationContainer>

Or with the hook:

import { useHideSplash } from 'react-native-splash-motion';

function App() {
  const [fontsLoaded] = useFonts(fonts);
  useHideSplash(fontsLoaded, { outro: 'outro' });
  // …
}

API

hide(options?): Promise<void>

Resolves once the splash is fully gone. All options are optional.

| Option | Default | Description | | ------------- | ------- | ------------------------------------------------------------------------ | | waitForLoop | true | Let the current loop finish instead of cutting the animation mid-motion. | | outro | — | A marker name to play before leaving. | | minDuration | 0 | Keep the splash visible at least this long (ms since launch). | | fade | 220 | Fade-out duration in ms. 0 disables it. |

Order of events: minDuration → finish loop → outro → fade.

isVisible(): boolean

useHideSplash(ready?: boolean, options?)

Calls hide(options) as soon as ready is true.

CLI

npx splash-motion generate <animation> [options]

  <animation>               A Lottie .json or a dotLottie .lottie file

  --background <hex>        Background color              (default: #FFFFFF)
  --width <number>          Animation width in dp/pt      (default: 160)
  --height <number>         Animation height in dp/pt     (default: keeps aspect ratio)
                            Scaled down at runtime to fit 90% of the screen
  --still <png>             Your animation's first frame, shown by the launch screen (iOS + Android)
  --loop-marker <name>      Only loop this marker's range
  --no-loop                 Play once and hold the last frame
  --keep-background         Keep a full-canvas background solid in the animation (removed by default)
  --force                   Replace the iOS launch storyboard without keeping a .bak copy
  --platforms <list>        ios,android                   (default: both)
  --project-root <path>     Your app's root folder        (default: current directory)
  --version                 Print the installed splash-motion version

The Expo plugin accepts the same options in camelCase (loopMarker, keepBackground: true, …) plus source.

Check your setup

npx splash-motion doctor

Validates the generated assets, launch-screen wiring (the storyboard must be valid XML and generated by SplashMotion) and marker names, and warns about common conflicts (e.g. expo-splash-screen still installed). The marker check covers the configured loopMarker; outro is a runtime argument to hide() and is not validated here. Exits non-zero when something is broken, so you can use it in CI. On Expo without a native project yet, run npx expo prebuild first.

Background layers

Animations exported from After Effects often include a full-size background solid (e.g. a white "White Solid 1" layer). It would draw an opaque box over your splash color, so the CLI removes it automatically and logs what it removed. Only plain, fully opaque solids at the bottom of the layer stack that cover the whole canvas are removed. Shapes, images and anything animated, masked or used as a matte are left alone. Pass --keep-background to keep it.

Designing your animation

Add markers in After Effects (or LottieFiles):

  • loop → the section that repeats while the app loads (--loop-marker loop)
  • outro → the exit, played by hide({ outro: 'outro' })

Design frame 0 to sit on the same background color as your splash so the launch is seamless.

How it works

Tap icon ─▶ OS launch screen ─▶ native overlay (animation playing) ─▶ hide() ─▶ outro ─▶ your app
            (static, generated)   └── JS bundle loads in parallel ──┘
  1. Build time — the CLI / Expo plugin copies your animation (unpacking a .lottie to JSON) into the app's asset catalog (iOS) and assets/ (Android), generates a matching launch screen and theme, and records the config.
  2. Launch — the OS shows the static launch screen. SplashMotion installs itself automatically (+load on iOS, an init ContentProvider on Android), attaches a native overlay to the first window and starts the animation. On Android the animation is parsed in the background as soon as the process starts, and the system splash is held until its first frame is ready; the animation then starts from that frame, so the hand-off from the --still image is invisible.
  3. JS ready — hide() goes through Nitro straight to Swift/Kotlin, which runs the exit sequence and removes the overlay.

Testing

// jest.setup.js
jest.mock('react-native-splash-motion', () => ({
  __esModule: true,
  default: {
    hide: jest.fn().mockResolvedValue(undefined),
    isVisible: jest.fn(() => false),
  },
  useHideSplash: jest.fn(),
}));

Troubleshooting

  • Not sure what's wrong? — run npx splash-motion doctor. It checks the generated setup, marker names and common conflicts, and exits non-zero on errors.

  • Nothing changed — native assets only update on a rebuild. Re-run pod install and rebuild; a JS reload isn't enough.

  • iOS shows the old launch screen, then the new background — iOS caches a snapshot of the launch screen and only refreshes it when the app is reinstalled. Delete the app from the device or simulator (or run xcrun simctl uninstall booted <bundle id>), then build again.

  • Expo shows the old splash — make sure expo-splash-screen is removed, then npx expo prebuild --clean.

Roadmap

  • Automatic first-frame extraction for --still
  • Dark-mode background (--dark-background) that stays seamless on iOS too
  • Per-platform animations and sizes
  • Rive (.riv) animation support

Contributing

See the contributing guide. After changing src/SplashMotion.nitro.ts, run yarn nitrogen.

License

MIT