donavon / splashr

A React component that takes the effort out of adding a Splash Screen to your web application.

🌊 Splashr

A React component that takes the effort out of adding a Splash Screen to your web application.

❤️ it? ⭐️ it on GitHub or Tweet about it.

New in Version 0.3.x

• Support for React Suspense and lazy loading of components (see below for details)!

Installation

$ npm i splashr

or

$ yarn add splashr

⚠️ Note: Splashr has a peerDependency on React 16.8.0 or greater.

Basic Usage

Here is a simple example use of Splashr.

import Splashr from 'splashr';

const splash = (
  <div className="splash-screen">
    Welcome to my app
  </div>
);

const App = () => (
  <Splashr splash={splash}>
    <div className="app">
      This is my app.
    </div>
  </Splashr>
);

Props

Here are some of the props that you can use to customize Splashr. (* = required)

Parameter	Description
splash*	Your rendered splash screen.
children*	Your app.
minDelay	How long to show the splash screen in msecs. Default = 2000
extend	A boolean that will extend the splash screen. Set to true to extend the splash screen past minDelay, maybe to load a resource. Default = false.
transitionTime	By default, Splashr will transition between the splash screen and your app. This value will set the transition time in msecs. To disable the transition, set transitionTime to 0. Default = 700
transitionTimingFunction	The string representing the timing function to perform on the transition. Default = "ease"

Suspense

Starting with version 0.3.0, there is support for React Suspense and lazy loading.

Let's say you lazy load some components. With Suspense, the splash screen will remin visible for at least 2 seconds (by default, or whatever value you speify in minDelay), but possibly longer if the components have yet to load. This is very useful for slower 2G/3G connections on mobile devices.

One might do this to get the splash screen rendered as soon as possible while the rest of the app is sill loading (or First Meaningful Paint).

To support Suspense, simply change <Splashr> to <Splashr.Suspense>. All props are supported except extend, which is ignored with <Splashr.Suspense>.

import Splashr from 'splashr';

const OtherComponent = React.lazy(() => import('./OtherComponent'));
const AnotherComponent = React.lazy(() => import('./AnotherComponent'));

const splash = (
  <div className="splash-screen">
    Welcome to my app
  </div>
);

const App = () => (
  <Splashr.Suspense splash={splash}>
    <div className="app">
      <OtherComponent />
      <AnotherComponent />
    </div>
  </Splashr.Suspense>
);

Why not just use React's Suspense?

Splashr.Suspense is simular to React's built-in Suspense (in fact it's built on top of it), but supports a smooth transition between the splash screen and the rest of the app. it also supports a minDelay, which React's Suspense does not.

Sample Apps

Here is a list of apps build with Splashr. If you have an app you would like to include on this list, open a PR.

• Demo App on CodeSandbox - by @donavon
• Splash.Suspense demo on CodeSandbox - by @donavon

License

MIT Licensed

Contributors

Thanks goes to these wonderful people (emoji key):

Donavon West 🚇 ⚠️ 💡 🤔 🚧 👀 🔧 💻	Jack Cross 🤔 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

splashr's Issues

add contributors

onCompleted callback

Hello, nice work on this.
I'm in the need to know when Splash.Suspense finished loading content and has already faded out. The reason behind this is that after loading everything I need to start playing multimedia content, and it will almost always delay more than the minDelay time, but due to caching it might not have any delay, and having a sound you can't interact with is frown upon :)

Support React Suspense

I think React Suspense opens up the possibility of showing the splash screen until your app is loaded, maybe the component could look something like:

const SplashrSuspense = ({ splash, children }) => {
  // Show the fallback immediately on the first render, but then never again
  const [maxDuration, setMaxDuration] = React.useState(0);
  React.useEffect(
    () => {
      setMaxDuration(Infinity);
    },

    []
  );

  return (
    <React.Suspense maxDuration={maxDuration} fallback={splash}>
      {children}
    </React.Suspense>
  );
}; 

export default;

Then you could add it to the Splashr export:

import SplashrSuspense from './SplashrSuspense';

// ... Splashr code

Splashr.Suspense = SplashrSuspense;

export default Splashr;

And then usage would look like:

import Splashr from 'splashr';

const splash = <div className="splash-screen">Welcome to my app</div>;

const App = () => (
  <Splashr.Suspense splash={splash}>
    <div className="app">This is my app.</div>
    {/** other code that suspends! */}
  </Splashr.Suspense>
);

I think you would still need to add the transition animation, but let me know what you think!