react-scrim

A scrim store for React. Declare the nodes and how they animate once, then cover and uncover from anywhere, route loaders included.

Package: npmjs.com/package/react-scrim

Documentation: dev.robertoattanasio.com/react-scrim

Install

npm install react-scrim

Usage

import { createScrim } from "react-scrim";

export const scrimRouteConfig = createScrim({
  nodes: ["curtain"],
  animation: { duration: 650, easing: "cubic-bezier(0.65, 0, 0.35, 1)" },
  hold: 1000,
  until: () => document.fonts.ready,
  enter: ({ curtain }, { status, play }) =>
    play(
      curtain,
      status === "idle"
        ? [{ transform: "translateY(100%)" }, { transform: "translateY(0)" }]
        : [{ transform: "translateY(0)" }],
    ),
  leave: ({ curtain }, { play }) => play(curtain, [{ transform: "translateY(-100%)" }]),
});

<div ref={scrimRouteConfig.node("curtain")} className="fixed inset-0" />

export const Route = createFileRoute("/about")({
  loader: () => scrimRouteConfig.cover(),
});

router.subscribe("onResolved", () => scrimRouteConfig.uncover());

import { useScrim } from "react-scrim";

const { status, isReady } = useScrim(scrimRouteConfig);

Timing

The store has no idea how long anything takes. cover and uncover don't carry a duration — they call enter/leave and wait for whatever those return, which in practice is play's return value: the same Animation.finished promise the browser resolves once the animation actually on screen has actually finished. There's nowhere else the time is written down, so there's nothing to keep in sync — no CSS duration to match against a JS timer, no transitionend that fires twice for two properties or not at all when an animation is replaced mid-flight.

leave can compose more than one play call — a curtain and a page, each with its own delay, duration and easing — and uncover still just awaits the result. It doesn't know either duration; it waits for whichever finishes last. The choreography is a consequence of what's composed, not a number anyone maintains.

hold is the one exception: a fixed pause the store keeps for itself, deliberately, between being ready and starting to leave.

Why this also means an interrupted navigation just works: dev.robertoattanasio.com/react-scrim for the idea, /react-scrim/create-scrim#section-interruptions for how.

Options

| option | what it does | | ----------- | --------------------------------------------------------------------------------------------- | | nodes | the names of the nodes the store animates | | initial | "covered" (default) starts covering, for a splash. "idle" starts uncovered | | animation | default options for every play call | | hold | milliseconds to stay covered before leaving | | until | what to wait for before the first leave | | enter | the enter animation. status is "idle" when starting from rest, "leaving" when reversing | | leave | the leave animation |

enter, leave and until can return anything that can be awaited, so GSAP and Motion work in place of play.

Store

| method | what it does | | -------------- | -------------------------------------------------- | | node(name) | a ref that registers a node | | cover() | runs enter. Resolves once covered | | uncover() | waits for until and hold, then runs leave | | subscribe | listens to every change | | getStatus() | "idle", "entering", "covered" or "leaving" | | getIsReady() | true once until has resolved |

License

MIT