Gradient Reveal Text

"use client";

import * as React from "react";
import { motion, useScroll, useSpring, useTransform, type MotionValue } from "motion/react";

/* SSR-safe: renders "no preference" on the server and the first client pass, so markup always hydrates. */
function subscribeReducedMotion(onChange: () => void) {
  const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
  mq.addEventListener("change", onChange);
  return () => mq.removeEventListener("change", onChange);
}

function usePrefersReducedMotion() {
  return React.useSyncExternalStore(
    subscribeReducedMotion,
    () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
    () => false,
  );
}
type ScrollOffset = NonNullable<NonNullable<Parameters<typeof useScroll>[0]>["offset"]>;

export interface GradientRevealTextProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
  /** The paragraph text. */
  children: string;
  /** Element to render. */
  as?: "p" | "h2" | "h3" | "blockquote" | "div";
  /** Scrollable ancestor to track. Defaults to the window. */
  container?: React.RefObject<HTMLElement | null>;
  /** Reveal words from first to last, or from last to first. */
  direction?: "forward" | "reverse";
  /** Gradient start colour (any CSS colour). */
  accent?: string;
  /** Gradient end colour (any CSS colour). Deepened automatically on light backgrounds. */
  accentSecondary?: string;
  /** Opacity of words that have not been revealed yet (0–1). */
  dimOpacity?: number;
  /** How many words are mid-transition at once — higher is softer. */
  softness?: number;
  /** Smooth scroll progress with a light spring. */
  smooth?: boolean;
  /** Scroll offsets, as in motion's useScroll: when the reveal starts and ends. */
  offset?: ScrollOffset;
}

const DEFAULT_OFFSET: ScrollOffset = ["start 0.85", "end 0.45"];

/** Mixes the two accents for word `index` of `total`, so the paragraph reads as one gradient. */
function wordColor(index: number, total: number) {
  const share = total <= 1 ? 100 : Math.round((1 - index / (total - 1)) * 100);
  return `color-mix(in oklab, var(--grt-a) ${share}%, var(--grt-b))`;
}

interface WordProps {
  word: string;
  color: string;
  progress: MotionValue<number>;
  /** Position in reveal order (0 = first revealed). */
  order: number;
  total: number;
  softness: number;
}

function RevealWord({ word, color, progress, order, total, softness }: WordProps) {
  // Spread the scroll range over the words; each takes `softness` words' worth of progress to fade in.
  const reveal = useTransform(progress, (p) =>
    Math.min(1, Math.max(0, (p * (total + softness) - order) / softness)),
  );
  // The dim base fades out as the accent layer fades in, so the two never muddy together.
  const base = useTransform(reveal, (r) => 1 - r);

  return (
    <span className="relative inline-block">
      <motion.span className="text-zinc-900 dark:text-zinc-100" style={{ opacity: base }}>
        <span className="opacity-[var(--grt-dim)]">{word}</span>
      </motion.span>
      <motion.span className="absolute inset-0" style={{ opacity: reveal, color }}>
        {word}
      </motion.span>
    </span>
  );
}

/**
 * A paragraph whose words take on an accent gradient as it scrolls through the viewport
 * (or through any scrollable container passed via `container`).
 */
export function GradientRevealText({
  children,
  as = "p",
  container,
  direction = "forward",
  accent = "#FF7448",
  accentSecondary = "#B6F3D1",
  dimOpacity = 0.18,
  softness = 3,
  smooth = true,
  offset = DEFAULT_OFFSET,
  className = "",
  style,
  ...props
}: GradientRevealTextProps) {
  const reduceMotion = usePrefersReducedMotion();
  const ref = React.useRef<HTMLElement>(null);
  const { scrollYProgress } = useScroll({ target: ref, container, offset });
  const smoothed = useSpring(scrollYProgress, { stiffness: 160, damping: 30, mass: 0.4, restDelta: 0.0005 });
  const progress = smooth ? smoothed : scrollYProgress;
  const Tag = as as React.ElementType;

  const words = children.split(/\s+/).filter(Boolean);
  const total = words.length;

  return (
    <Tag
      ref={ref}
      className={
        // On light backgrounds the accents are deepened towards ink so revealed words keep their contrast.
        "[--grt-a:color-mix(in_oklab,var(--grt-accent)_82%,#18181b)] [--grt-b:color-mix(in_oklab,var(--grt-accent-2)_48%,#18181b)] " +
        "dark:[--grt-a:var(--grt-accent)] dark:[--grt-b:var(--grt-accent-2)] " +
        className
      }
      style={{
        ["--grt-accent" as string]: accent,
        ["--grt-accent-2" as string]: accentSecondary,
        ["--grt-dim" as string]: Math.min(1, Math.max(0, dimOpacity)),
        ...style,
      }}
      {...props}
    >
      <span className="sr-only">{children}</span>
      <span aria-hidden="true">
        {words.map((word, i) => {
          const color = wordColor(i, total);
          return (
            <React.Fragment key={i}>
              {i > 0 && " "}
              {reduceMotion ? (
                // Static, fully revealed version.
                <span style={{ color }}>{word}</span>
              ) : (
                <RevealWord
                  word={word}
                  color={color}
                  progress={progress}
                  order={direction === "forward" ? i : total - 1 - i}
                  total={total}
                  softness={Math.max(1, softness)}
                />
              )}
            </React.Fragment>
          );
        })}
      </span>
    </Tag>
  );
}