create Scrim

Create a scrim, mount its `Root` around the page, then use `cover()` and `uncover()` to control its curtains.

Usage

I create one scrim per kind of cover, next to the curtain it starts with. It lives outside React, so a route, the router or a plain function can call it. Its Root goes around everything the curtains should cover.

tsx
// features/app.scrim.tsx
export const AppScrim = createScrim(AppCurtain, {
  hold: 650,
  until: () => document.fonts.ready,
});

// screens/app/app-root.tsx
<AppScrim.Root>
  <Outlet />
</AppScrim.Root>

The curtain

A curtain gets a single prop, scrim, with its phase, its meta and done. It animates however it likes, and calls done() once when the entrance ends and once more when the exit ends.

tsx
export const AppCurtain = ({ scrim }: ScrimProps) => (
  <m.div
    initial={scrim.phase === "covered" ? false : { x: "-100%" }}
    animate={{ x: scrim.phase === "leaving" ? "100%" : "0%" }}
    transition={{ duration: 0.65 }}
    onAnimationComplete={() => scrim.done()}
    className="fixed inset-0 z-max bg-primary-darken"
  />
);

cover and uncover

cover() mounts a curtain on top and resolves once it has covered, so whatever comes next can wait for it. uncover() waits for the top curtain's until and hold, then lets it leave.

tsx
await AppScrim.cover(MargoUiScrim);

AppScrim.uncover();

Every cover() adds a curtain, even one identical to the last. Deciding when to cover belongs to the app: the route transitions example shows how I skip it between pages of the same section.

Options

Every curtain carries its own options. hold and until decide when it may leave. key is your own id, so you can tell which curtain is on top. meta is your own data: react-scrim never reads it, it just hands it back to the curtain and to useStatus.

tsx
type AppScrimMeta = { duration: number; ease: [number, number, number, number] };

export const AppScrim = createScrim(AppCurtain, {
  meta: { duration: 0.65, ease: [0.65, 0, 0.35, 1] },
});

AppScrim.cover(MargoUiScrim, {
  key: "/margo-ui",
  hold: 650,
  meta: { duration: 0.45, ease: [0.22, 1, 0.36, 1] },
});

const MargoUiScrim = ({ scrim }: ScrimProps<AppScrimMeta>) => (
  <m.div transition={scrim.meta} />
);

Other animation tools

Use any animation tool that tells you when an animation ends. With CSS, pass done straight to onAnimationEnd; events bubbling up from the curtain's children are ignored.

tsx
const Curtain = ({ scrim }: ScrimProps) => (
  <div
    className={scrim.phase === "leaving" ? "animate-curtain-out" : "animate-curtain-in"}
    onAnimationEnd={scrim.done}
  />
);

Reference

Arguments

proptypedefault
initial?ScrimCurtain—the curtain on the first paint. Without it, the page starts uncovered
options?ScrimOptions—the options of that curtain

Options

proptypedefault
hold?number0milliseconds to stay covered before leaving
until?() => unknown—what to wait for before leaving
key?string—your own id, read back by useStatus and getStatus
meta?TMeta—your own data, read back by the curtain and by useStatus

Returns

proptypedefault
Root({ children }) => ReactNode—renders its children and the curtains on top of them
cover(curtain, options?) => Promise<void>—mounts a curtain on top; resolves once it has covered
uncover() => Promise<void>—lets the top curtain leave
useStatus() => ScrimState—the top curtain, inside Root
getStatus() => ScrimState | undefined—the same outside React, undefined before Root mounts

Curtain props

proptypedefault
scrim.phase"entering" | "covered" | "leaving"—where the curtain is
scrim.metaReadonly<TMeta>—its meta
scrim.done(event?) => void—call it when the entrance or the exit has ended