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.
// 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.
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.
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.
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.
const Curtain = ({ scrim }: ScrimProps) => (
<div
className={scrim.phase === "leaving" ? "animate-curtain-out" : "animate-curtain-in"}
onAnimationEnd={scrim.done}
/>
);Reference
Arguments
| prop | type | default | |
|---|---|---|---|
initial? | ScrimCurtain | — | the curtain on the first paint. Without it, the page starts uncovered |
options? | ScrimOptions | — | the options of that curtain |
Options
| prop | type | default | |
|---|---|---|---|
hold? | number | 0 | milliseconds 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
| prop | type | default | |
|---|---|---|---|
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
| prop | type | default | |
|---|---|---|---|
scrim.phase | "entering" | "covered" | "leaving" | — | where the curtain is |
scrim.meta | Readonly<TMeta> | — | its meta |
scrim.done | (event?) => void | — | call it when the entrance or the exit has ended |