Intro Loader

npm install motion clsx tailwind-merge

import { clsx, type ClassValue } from "clsx";
import { extendTailwindMerge } from "tailwind-merge";

/* tailwind-merge must know the site's type scale (globals.css) is a font size, not a text color — otherwise
   cn("text-h6 text-muted-foreground") drops text-h6. */
const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "h5", "h6"] }] } },
});

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";
import { cn } from "@/lib/utils";

/*
 * Intro Loader — a full-screen preloader (from the Catchup Home "Loader"). A cover in the foreground colour fills the first
 * screen. A window sits in the middle, and the photos rise into it one after another, each over the last. Then the mark
 * rises from below the screen to 20px under the window, and the window moves up half the pair's height to keep it centred.
 * After a hold the photos leave upwards, the mark flies off the top, and one step later the cover shrinks upwards and
 * uncovers the page, about 3.6s in all. Every move is Framer's tween T1: 1s, cubic-bezier(.59,.25,.12,1.17), which
 * overshoots about 3% and comes back.
 *
 * Mount it at the top of the page, not inside a positioned element: the cover is absolute, not fixed, so it scrolls
 * away with the page, which is not locked, and it never takes a click or a key (pointer-events none). Anything on the
 * page that animates in on load plays behind the cover, so give it a delay of about 2.6s or let the page simply be revealed.
 *
 * Whether it plays is decided before the first paint, by an inline script right after the cover: it plays once per browser
 * session (`once`), never for a visitor who asked for reduced motion, and never without JavaScript — the cover stays
 * `display: none` until the script shows it. The script puts `data-intro="play"` (or "done") on the cover itself, so
 * the page's own <html> is left alone; the cover carries suppressHydrationWarning because of that attribute. Arriving
 * by a client-side navigation no script runs, and the same decision is made in a layout effect, still before the paint.
 *
 * The moves are CSS transitions on transforms, driven by a few timers: nothing but the compositor draws the intro. Sizes
 * inside use container units (cqh), so it fills a screen or any box the same way.
 */

const ease = "cubic-bezier(.59,.25,.12,1.17)";
const tween = (delay = 0) => `transform 1s ${ease} ${delay}s`;

export type IntroLoaderProps = {
  /** The photos that rise into the window, in the order they arrive: each lands over the one before, so the last is on top when they leave. */
  images: React.ReactNode[];
  /** The mark that rises under the window once the photos are in: a logo, a wordmark. It takes the colour of the page behind the cover. */
  mark?: React.ReactNode;
  /** Seconds before the first photo starts. */
  delay?: number;
  /** Seconds between one photo and the next, the mark after the last photo, and the cover after everything has left. */
  step?: number;
  /** Seconds the window and the mark hold before they leave. */
  hold?: number;
  /** Width of the window, in px. */
  windowWidth?: number;
  /** Height of the window, in px. */
  windowHeight?: number;
  /** Space between the window and the mark, in px. */
  gap?: number;
  /** How often it plays: once per browser session, once ever, or on every page load. */
  once?: "session" | "forever" | false;
  /** The key a visit is remembered under, so two loaders on one site keep apart. */
  storageKey?: string;
  /** Classes for the cover: its colour, its layer (z-50, over a sticky header), its height (h-full inside a box). */
  className?: string;
};

const noop = () => () => {};

/* The decision, as the script makes it: play unless this visit has seen it or the visitor asked for reduced motion. */
function decide(once: IntroLoaderProps["once"], key: string) {
  let seen = false;
  try {
    if (once) seen = Boolean((once === "forever" ? localStorage : sessionStorage).getItem(key));
  } catch {
    seen = true;
  }
  return !seen && !window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "play" : "done";
}

function script(once: IntroLoaderProps["once"], key: string) {
  const seen = once ? `${once === "forever" ? "localStorage" : "sessionStorage"}.getItem(${JSON.stringify(key).replace(/</g, "\\u003c")})` : "false";
  return `try{var e=document.currentScript.previousElementSibling;e.dataset.intro=!${seen}&&!matchMedia("(prefers-reduced-motion: reduce)").matches?"play":"done"}catch(x){}`;
}

export function IntroLoader({
  images,
  mark,
  delay = 0.1,
  step = 0.3,
  hold = 1,
  windowWidth = 268,
  windowHeight = 200,
  gap = 20,
  once = "session",
  storageKey = "intro-loader",
  className,
}: IntroLoaderProps) {
  const root = React.useRef<HTMLDivElement>(null);
  const markBox = React.useRef<HTMLDivElement>(null);
  /* 0 waiting, 1…n photo n has arrived, n + 1 the mark has joined, n + 2 everything leaves. */
  const [stage, setStage] = React.useState(0);
  const [lift, setLift] = React.useState(0);
  const [finished, setFinished] = React.useState(false);
  /* The script is in the server's HTML and in the first client render, which has to match it; a cover that mounts on the client has none to run. */
  const withScript = React.useSyncExternalStore(noop, () => false, () => true);
  const count = images.length;
  const hasMark = Boolean(mark);

  /* Before the first paint, so the page never shows for a moment before the cover. */
  React.useLayoutEffect(() => {
    const element = root.current;
    if (!element) return;
    if (!element.dataset.intro) element.dataset.intro = decide(once, storageKey);
    if (element.dataset.intro !== "play") {
      setFinished(true);
      return;
    }
    if (once) {
      try {
        (once === "forever" ? localStorage : sessionStorage).setItem(storageKey, "1");
      } catch {}
    }
    /* The window rises half of (mark + gap) when the mark joins, which keeps the pair centred. */
    setLift(hasMark && markBox.current ? (markBox.current.offsetHeight + gap) / 2 : 0);
    setStage(0);
    const arrivals = Array.from({ length: count }, (_, index) => delay + index * step);
    const joinsAt = delay + count * step;
    const leavesAt = joinsAt + hold;
    /* The last time is the cover having shrunk (one step of delay and its second), with a little room, when it is taken away. */
    const times = [...arrivals, joinsAt, leavesAt, leavesAt + step + 1.2];
    const timers = times.map((time, index) => window.setTimeout(() => (index === times.length - 1 ? setFinished(true) : setStage(index + 1)), time * 1000));
    return () => timers.forEach((timer) => window.clearTimeout(timer));
  }, [count, hasMark, delay, step, hold, gap, once, storageKey]);

  if (finished) return null;

  const joined = stage >= count + 1;
  const leaving = stage >= count + 2;
  /* Photos come from, and go to, this far below and above the window. */
  const travel = windowHeight + 150;
  /* The mark's top, below the middle, once it has joined; and how far it has to move to be off the bottom and off the top. */
  const below = windowHeight / 2 - lift + gap;

  return (
    <>
      <div
        ref={root}
        aria-hidden
        suppressHydrationWarning
        className={cn(
          "pointer-events-none absolute inset-x-0 top-0 z-50 hidden h-screen [container-type:size] overflow-hidden data-[intro=play]:block print:hidden!",
          className,
        )}
      >
        <div
          className="absolute inset-0 origin-top bg-foreground"
          style={{ transform: leaving ? "translateY(-120px) scaleY(.01)" : "translateY(0px) scaleY(1)", transition: tween(leaving ? step : 0) }}
        />
        <div
          className="absolute inset-0 z-1 m-auto overflow-hidden"
          style={{ width: windowWidth, height: windowHeight, transform: `translateY(${joined && !leaving ? -lift : 0}px)`, transition: tween() }}
        >
          {images.map((image, index) => (
            <div
              key={index}
              className="absolute inset-0 [&>*]:size-full [&>*]:object-cover"
              style={{ transform: `translateY(${leaving ? -travel : stage >= index + 1 ? 0 : travel}px)`, transition: tween() }}
            >
              {image}
            </div>
          ))}
        </div>
        {hasMark && (
          <div
            ref={markBox}
            className="absolute inset-x-0 flex justify-center text-background"
            style={{
              top: `calc(50% + ${below}px)`,
              transform: leaving ? `translateY(calc(-50cqh - 100px - ${below}px))` : joined ? "translateY(0px)" : `translateY(calc(50cqh + 58px - ${below}px))`,
              transition: tween(),
            }}
          >
            {mark}
          </div>
        )}
      </div>
      {withScript && <script dangerouslySetInnerHTML={{ __html: script(once, storageKey) }} />}
    </>
  );
}