splashscreen-react 🚀

A frontend-only splash screen for React applications that waits until the app is actually ready (DOM, fonts, images) and then smoothly reveals the UI with animations.

Built for modern React apps. No backend. No fake timeouts. No flicker.

✨ Features

• ✅ Frontend-only readiness detection
• ⏳ Waits for DOM, fonts, and images
• 🎬 Smooth reveal animations
• 🧩 Works with lazy routes & React Router
• 🔒 Disables scroll during splash
• ⚡ Lightweight & tree-shakable
• 🧠 No content flash
• 🧪 Tested with React 18+

📦 Installation

npm install splashscreen-react

or

yarn add splashscreen-react

🚀 Basic Usage

import { SplashScreen } from 'splashscreen-react';

function FullscreenLoader() {
    return (
        <div className="flex h-full w-full flex-col items-center justify-center text-white">
            <div className="h-10 w-10 animate-spin rounded-full border-4 border-white/20 border-t-white" />
            <span className="mt-3 text-sm">Loading…</span>
        </div>
    );
}

export default function App() {
    return (
        <SplashScreen loader={<FullscreenLoader />} minDuration={1200} waitForFonts waitForImages animation={{ type: 'scale-fade', duration: 700 }}>
            <YourApp />
        </SplashScreen>
    );
}

🎬 Animations

Built-in animations

• fade
• scale-fade
• slide-up

Custom animation config

<SplashScreen animation={{ type: "scale-fade", duration: 800, easing: "ease-in-out" }}

⚙️ Props API

| Prop | Type | Default | Description | | ------------- | --------------- | --------------- | ------------------------ | | children | ReactNode | — | App or route content | | loader | ReactNode | Default spinner | Custom loader UI | | minDuration | number | 800 | Minimum splash time (ms) | | waitForFonts | boolean | true | Wait for fonts | | waitForImages | boolean | false | Wait for images | | animation | string / object | scale-fade | Reveal animation | | onReady | () => void | — | Called when splash ends |

🎨 Styling with CSS Variables

<SplashScreen style={{ "--ss-bg": "#0a0a0a", "--ss-duration": "700ms" }}

Available variables:

| Variable | Description | | ------------- | ----------------------- | | --ss-bg | Splash background color | | --ss-duration | Animation duration | | --ss-easing | Animation easing |

🧠 How It Works

1. React mounts

2. Splash screen appears

3. Waits for:

   • DOM ready
   • Fonts (optional)
   • Images (optional)
   • Minimum duration

4. Scroll is disabled

5. App is revealed with animation

6. Scroll is restored

4️⃣ Verify

npm view splashscreen-react

or visit:

https://www.npmjs.com/package/splashscreen-react

⚠️ Notes & Best Practices

• React is a peerDependency
• Splash runs only on initial mount
• Works with Vite, CRA, and client-side Next.js
• Avoid using h-screen inside loader

🛠 Troubleshooting

Loader never disappears

• Ensure app mounts correctly
• Check waitForImages on large images

Flash of content

• Ensure splash wraps the correct component
• Do not render content outside SplashScreen

Scroll issues

• Splash automatically locks scroll
• Avoid manual overflow overrides