Text Appear

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 { motion, useReducedMotion, type Transition } from "motion/react";

/*
 * Text Appear — a heading whose words rise into place out of a blur, one after another (from the Titen headings;
 * Ciketo has the same effect without the blur, which `blur={0}` gives).
 * It plays once: on load, or the first time it scrolls into view.
 *
 * Framer's springs are overdamped — no overshoot, settled in well under a second:
 *   words: from opacity 0, y 10, blur 7px, spring 320 / 58 / 1, each word 0.05s after the one before;
 *   lines: from y 7, spring 320 / 64 / 1 — `by="line"` moves the whole text at once.
 * Framer splits the text into letters, which breaks the kerning; whole words keep it.
 *
 * Reduced motion: <MotionConfig reducedMotion="user"> skips the movement but would keep animating opacity and blur,
 * so this checks useReducedMotion() itself and shows the text at once.
 * Screen readers get the sentence once, from an sr-only copy; the animated words are aria-hidden.
 * The words start at opacity 0 on the server, so the text appears when the page hydrates — keep `delay` short.
 */

const word: Transition = { type: "spring", stiffness: 320, damping: 58, mass: 1 };
const line: Transition = { type: "spring", stiffness: 320, damping: 64, mass: 1 };

export type TextAppearProps = {
  /** The text. It is split on spaces, so the kerning inside a word is never touched. */
  text: string;
  /** The element to render: a heading, a paragraph, anything. */
  as?: React.ElementType;
  /** "word" moves each word in turn; "line" moves the whole text at once. */
  by?: "word" | "line";
  /** "load" plays as soon as it mounts; "view" waits until it scrolls into view. Either way, once. */
  trigger?: "load" | "view";
  /** Seconds before it starts. */
  delay?: number;
  /** Seconds between words. */
  stagger?: number;
  /** Blur it starts from, in px; 0 turns the blur off (Ciketo). */
  blur?: number;
  /** How far it rises, in px. */
  distance?: number;
  className?: string;
};

export function TextAppear({
  text,
  as: Tag = "p",
  by = "word",
  trigger = "load",
  delay = 0,
  stagger = 0.05,
  blur = 7,
  distance,
  className,
}: TextAppearProps) {
  const reduce = useReducedMotion();
  const words = React.useMemo(() => text.split(" "), [text]);
  const rise = distance ?? (by === "word" ? 10 : 7);

  if (reduce) {
    return <Tag className={className}>{text}</Tag>;
  }

  const hidden = { opacity: 0, y: rise, filter: blur ? `blur(${blur}px)` : "blur(0px)" };
  const shown = { opacity: 1, y: 0, filter: "blur(0px)" };
  const inView = trigger === "view" ? { whileInView: "shown", viewport: { once: true, amount: 0.3 } } : { animate: "shown" };

  /* The element stays whatever `as` says; the orchestration sits on a span inside it, so no component is built
     during render (and the heading keeps its own styles). */
  return (
    <Tag className={className}>
      {/* The sentence, read once. */}
      <span className="sr-only">{text}</span>
      <motion.span
        aria-hidden
        initial="hidden"
        {...inView}
        variants={{ shown: { transition: { delayChildren: delay, staggerChildren: by === "word" ? stagger : 0 } } }}
        className="inline-block"
      >
        {by === "line" ? (
          <motion.span variants={{ hidden, shown }} transition={line} className="inline-block">
            {text}
          </motion.span>
        ) : (
          words.map((part, index) => (
            <React.Fragment key={`${part}-${index}`}>
              <motion.span variants={{ hidden, shown }} transition={word} className="inline-block">
                {part}
              </motion.span>
              {index < words.length - 1 && " "}
            </React.Fragment>
          ))
        )}
      </motion.span>
    </Tag>
  );
}