Stagger Text

1"use client"
2 
3import * as React from "react"
4 
5import { cn } from "@/lib/utils"
6 
7export interface StaggerTextProps extends Omit<
8  React.ComponentProps<"span">,
9  "children"
10> {
11  /** The text to reveal. Only plain text, so the split stays predictable. */
12  children: string
13  /** Split the text into words or into single characters. */
14  by?: "word" | "character"
15  /** Seconds between one unit starting and the next. */
16  stagger?: number
17  /** Seconds for a single unit to finish arriving. */
18  duration?: number
19  /** Seconds to wait before the first unit starts. */
20  delay?: number
21  /** Hold until the text scrolls into view instead of running on mount. */
22  startOnView?: boolean
23  /** Replay every time the text re-enters the viewport. */
24  repeat?: boolean
25  /** Render the finished state with no animation. */
26  disabled?: boolean
27}
28 
29/** Splits on whitespace but keeps the separators so spacing survives. */
30function split(text: string, by: "word" | "character") {
31  if (by === "character") {
32    return Array.from(text)
33  }
34  return text.split(/(\s+)/)
35}
36 
37export function StaggerText({
38  children,
39  className,
40  by = "word",
41  stagger = 0.04,
42  duration = 0.5,
43  delay = 0,
44  startOnView = false,
45  repeat = false,
46  disabled = false,
47  ...props
48}: StaggerTextProps) {
49  const ref = React.useRef<HTMLSpanElement>(null)
50  const [active, setActive] = React.useState(!startOnView)
51 
52  React.useEffect(() => {
53    if (!startOnView || disabled) {
54      return
55    }
56 
57    const node = ref.current
58    if (!node || typeof IntersectionObserver === "undefined") {
59      setActive(true)
60      return
61    }
62 
63    const observer = new IntersectionObserver(
64      ([entry]) => {
65        if (entry.isIntersecting) {
66          setActive(true)
67          if (!repeat) {
68            observer.disconnect()
69          }
70        } else if (repeat) {
71          setActive(false)
72        }
73      },
74      { threshold: 0.2 }
75    )
76 
77    observer.observe(node)
78    return () => observer.disconnect()
79  }, [startOnView, repeat, disabled])
80 
81  const units = React.useMemo(() => split(children, by), [children, by])
82 
83  return (
84    <span
85      ref={ref}
86      data-slot="stagger-text"
87      className={cn("inline-block", className)}
88      {...props}
89    >
90      {/* The whole string is announced once; the pieces are decoration. */}
91      <span className="sr-only">{children}</span>
92      <span aria-hidden="true">
93        {units.map((unit, index) => {
94          if (/^\s+$/.test(unit)) {
95// … truncated