"use client";

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

import { cn } from "@/lib/utils";

type RevealMode = "word" | "char";

type ScrollOffset = NonNullable<Parameters<typeof useScroll>[0]>["offset"];

type ScrollRevealTextProps = {
  text: string;
  className?: string;
  /**
   * Reveal by word or character
   * @default "word"
   */
  mode?: RevealMode;
  /**
   * Offset range for the scroll trigger
   * @default ["start 0.9", "start 0.2"]
   */
  offset?: ScrollOffset;
  /**
   * Optional scroll container ref. When provided, scroll progress is tracked
   * relative to this container instead of the viewport.
   */
  container?: React.RefObject<HTMLElement | null>;
};

type RevealToken = {
  value: string;
  key: string;
  isSpace: boolean;
};

type ScrollRevealTokenProps = {
  token: RevealToken;
  index: number;
  total: number;
  mode: RevealMode;
  scrollYProgress: MotionValue<number>;
};

function ScrollRevealToken({
  token,
  index,
  total,
  mode,
  scrollYProgress,
}: ScrollRevealTokenProps) {
  const start = index / total;
  const end = start + 1 / total;
  const opacity = useTransform(scrollYProgress, [start, end], [0, 1]);
  const y = useTransform(scrollYProgress, [start, end], [14, 0]);
  const spacingClass =
    mode === "word"
      ? token.isSpace
        ? "pr-2"
        : undefined
      : token.isSpace
      ? "w-2"
      : undefined;

  return (
    <motion.span
      style={{ opacity, y }}
      className={cn("inline-block", spacingClass)}
    >
      {token.value}
    </motion.span>
  );
}

function ScrollRevealText({
  text,
  className,
  mode = "word",
  offset = ["start 0.9", "start 0.2"] as ScrollOffset,
  container,
}: ScrollRevealTextProps) {
  const containerRef = React.useRef<HTMLSpanElement | null>(null);
  const { scrollYProgress } = useScroll({
    target: containerRef,
    container,
    offset,
  });

  const tokens = React.useMemo<RevealToken[]>(() => {
    if (mode === "char") {
      return Array.from(text).map((char, index) => ({
        value: char,
        key: `${char}-${index}`,
        isSpace: char === " ",
      }));
    }

    return text.split(" ").map((word, index, array) => ({
      value: word,
      key: `${word}-${index}`,
      isSpace: index < array.length - 1,
    }));
  }, [mode, text]);

  return (
    <span
      ref={containerRef}
      className={cn("inline-flex flex-wrap text-foreground", className)}
    >
      {tokens.map((token, index) => (
        <ScrollRevealToken
          key={token.key}
          token={token}
          index={index}
          total={tokens.length}
          mode={mode}
          scrollYProgress={scrollYProgress}
        />
      ))}
    </span>
  );
}

export { ScrollRevealText };
Scroll Reveal Text

Dependencies

Files

Installation
