"use client";

import * as React from "react";
import { motion, useInView, type HTMLMotionProps, Variants } from "framer-motion";
import { cn } from "@/lib/utils";

type RevealMode = "letter" | "word";

interface AnimatedTextRevealProps extends HTMLMotionProps<"div"> {
  /**
   * The text to reveal
   */
  text: string;
  /**
   * Reveal mode - letter by letter or word by word
   * @default "word"
   */
  mode?: RevealMode;
  /**
   * Delay before animation starts (in seconds)
   * @default 0
   */
  delay?: number;
  /**
   * Duration of each element animation (in seconds)
   * @default 0.5
   */
  duration?: number;
  /**
   * Stagger delay between each element (in seconds)
   * @default 0.03 for letters, 0.08 for words
   */
  stagger?: number;
  /**
   * Animation direction
   * @default "up"
   */
  direction?: "up" | "down" | "left" | "right";
  /**
   * Trigger animation only once
   * @default true
   */
  once?: boolean;
  /**
   * Render as different element
   * @default "p"
   */
  as?: "p" | "h1" | "h2" | "h3" | "h4" | "span" | "div";
}

function AnimatedTextReveal({
  text,
  mode = "word",
  delay = 0,
  duration = 0.5,
  stagger,
  direction = "up",
  once = true,
  className,
  as: Component = "p",
}: AnimatedTextRevealProps) {
  const ref = React.useRef<HTMLDivElement>(null);
  const isInView = useInView(ref, { once, margin: "-10% 0px -10% 0px" });

  const defaultStagger = mode === "letter" ? 0.03 : 0.08;
  const actualStagger = stagger ?? defaultStagger;

  const elements = React.useMemo(() => {
    if (mode === "letter") {
      return text.split("").map((char, i) => ({
        char: char === " " ? "\u00A0" : char,
        key: `${char}-${i}`,
      }));
    }
    return text.split(" ").map((word, i) => ({
      char: word,
      key: `${word}-${i}`,
    }));
  }, [text, mode]);

  const getInitialPosition = () => {
    switch (direction) {
      case "up":
        return { y: 20, x: 0 };
      case "down":
        return { y: -20, x: 0 };
      case "left":
        return { y: 0, x: 20 };
      case "right":
        return { y: 0, x: -20 };
    }
  };

  const containerVariants: Variants = {
    hidden: {},
    visible: {
      transition: {
        delayChildren: delay,
        staggerChildren: actualStagger,
      },
    },
  };

  const itemVariants: Variants = {
    hidden: {
      opacity: 0,
      ...getInitialPosition(),
    },
    visible: {
      opacity: 1,
      y: 0,
      x: 0,
      transition: {
        duration,
        ease: [0.2, 0.65, 0.3, 0.9],
      },
    },
  };

  return (
    <motion.div
      ref={ref}
      variants={containerVariants}
      initial="hidden"
      animate={isInView ? "visible" : "hidden"}
      aria-label={text}
      className={cn("overflow-hidden", className)}
    >
      <Component className="m-0">
        {elements.map(({ char, key }) => (
          <motion.span
            key={key}
            variants={itemVariants}
            className={cn(
              "inline-block text-foreground",
              mode === "word" && "mr-[0.25em]"
            )}
          >
            {char}
          </motion.span>
        ))}
      </Component>
    </motion.div>
  );
}

export { AnimatedTextReveal };
Animated Text Reveal

Dependencies

Files

Installation
