Interlude

Keep a loading screen over your page until it’s ready. You choose the animation.

Usage

Wrap your page in Interlude and pass it a curtain. It stays covered until the page is ready:

tsx
import { Interlude } from "react-interlude";

const App = () => (
  <Interlude curtain={Curtain} hold={650} until={() => document.fonts.ready}>
    <Page />
  </Interlude>
);

The curtain component

Your curtain receives an interlude prop with its current phase and a done callback. Call done when its entrance or exit animation finishes. This example fades out using CSS:

tsx
const Curtain = ({ interlude }) => (
  <div className="curtain" data-phase={interlude.phase} onTransitionEnd={interlude.done} />
);
css
.curtain {
  position: fixed;
  inset: 0;
  background: black;
  transition: opacity 0.5s;
}

.curtain[data-phase="leaving"] {
  opacity: 0;
}

You can pass done directly to onTransitionEnd or onAnimationEnd. It ignores events from child elements, as well as callbacks left over from an earlier phase.

Waiting for the page to be ready

until returns a promise for work that should finish before people see the page, such as loading fonts or data. It receives an AbortSignal, which is triggered if another cover() starts while the promise is still pending:

tsx
<Interlude
  curtain={Curtain}
  until={(signal) => Promise.all([document.fonts.ready, fetch("/api/me", { signal })])}
/>

hold sets the minimum time, in milliseconds, that the curtain stays covered. Its timer starts when the curtain reaches covered and runs alongside until. The curtain leaves when both have finished. If another animation needs to finish too, include it in until.

Start with the page visible

Set initial="idle" to show the page immediately. The curtain appears the first time you call cover():

tsx
<Interlude curtain={Curtain} initial="idle">
  <Page />
</Interlude>

Keeping the curtain on the page

By default the curtain is unmounted once it has left. With persist it stays mounted, with its phase set to idle, so it can turn into something else on the page, like a logo:

tsx
const Curtain = ({ interlude }) => (
  <div
    className={interlude.phase === "idle" ? "logo" : "curtain"}
    onTransitionEnd={interlude.done}
  />
);

<Interlude curtain={Curtain} persist>
  <Page />
</Interlude>;

The next cover() doesn't mount a new curtain: the same component moves to entering, so it can start its entrance from wherever it was sitting. It works with initial="idle" too: the curtain is on the page from the start, already idle.

Passing data to the curtain

Use meta to pass any value to the curtain and to useInterlude, such as a duration both can use. Define the value outside your component so it stays the same between renders; creating a new object on every render triggers updates for everyone reading it:

tsx
const META = { duration: 0.65 };

<Interlude curtain={Curtain} meta={META} />;

Reference

Interlude

proptypedefault
curtainComponentType<InterludeProps>—the loading screen component
children?ReactNode—the page shown beneath the loading screen
initial?"covered" | "idle""covered"whether to cover the page on the first render
hold?number0minimum time to keep the page covered, in milliseconds
until?(signal: AbortSignal) => Promise<unknown>—a promise that resolves when the page is ready
meta?TMeta—data available to the loading screen and to useInterlude
persist?booleanfalsekeeps the curtain mounted when it's idle

Curtain

proptypedefault
interlude.phase"entering" | "covered" | "leaving" | "idle"—where the curtain is; idle only with persist
interlude.done(event?: SyntheticEvent) => void—call when the entrance or exit animation finishes
interlude.metaTMeta—the value passed to Interlude