SplitText (React)

React wrapper for splitText() with lifecycle handling and viewport callbacks.

import { SplitText } from "griffo/react";

SplitText is available in two React entry points:

• griffo/react (this page) — imperative callbacks for full control over animations.
• griffo/motion — declarative Motion-powered animations. See the Motion API.

For text morphing between changing strings, see MorphText (griffo/morph).

Props

Common wrapper DOM props (id, role, tabIndex, aria-*, data-*, and handlers like onClick) are forwarded to the wrapper.

SplitTextOptions

type SplitType =
  | "chars"
  | "words"
  | "lines"
  | "chars,words"
  | "words,lines"
  | "chars,lines"
  | "chars,words,lines";

type MaskType = "chars" | "words" | "lines";

Callback Signature

All callbacks receive the same result object:

interface SplitTextElements {
  chars: HTMLSpanElement[];
  words: HTMLSpanElement[];
  lines: HTMLSpanElement[];
  revert: () => void;
}

Callback props can return animations/promises:

type CallbackReturn =
| void
| { finished: Promise<unknown> }
| Array<{ finished: Promise<unknown> }>
| Promise<unknown>;

onRevert is a separate zero-argument callback that fires when a split cycle actually reverts.

With autoSplit + lines, reattach scroll/timeline logic in onResplit so it uses the new split elements.

Font Loading

React and Motion components wait for document.fonts.ready by default (waitForFonts={true}) for stable kerning.

If you need immediate splitting, opt out:

<SplitText waitForFonts={false}>
  <h1>Split immediately</h1>
</SplitText>

For vanilla JavaScript usage, see the vanilla API docs.

Accessibility

Griffo handles accessibility automatically. For elements that support aria-label (headings, landmarks), it labels the parent. For generic elements (<span>, <div>, <p>) and nested inline content, it keeps a screen-reader-only copy and hides visual split nodes from assistive tech. Existing aria-label values are preserved.

See the vanilla API docs for details.

Motion Component

The Motion component (griffo/motion) adds declarative animation props — initial, animate, whileInView, whileScroll, whileHover, and more — powered by Motion. It requires the motion package.

See the Motion API for the full reference, supported shapes, and trigger priority rules.

Morph Component

The Morph component (griffo/morph) is a dedicated API for text morphing between string updates with persistent character identity and built-in enter/exit transitions.

Examples

Basic

Wrap any element with SplitText and animate in onSplit.

import { SplitText } from "griffo/react";
import { animate, stagger } from "motion";

<SplitText
  onSplit={({ words }) => {
    animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
  }}
>
  <h1>Animated Text</h1>
</SplitText>;

Viewport Detection

Use viewport for scroll-triggered animations. Set the start state with initialStyles, and enable resetOnViewportLeave for repeat animations. By default, reset happens when the element is fully out of view; set viewport.leave to trigger sooner.

<SplitText
  options={{ type: "words" }}
  initialStyles={{
    words: { opacity: 0, transform: "translateY(20px)" },
  }}
  viewport={{ amount: 0.5 }}
  onViewportEnter={({ words }) =>
    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.05) })
  }
  resetOnViewportLeave
>
  <p>Animates when scrolled into view</p>
</SplitText>

For one-time animations, use once: true in the viewport options:

<SplitText
  initialStyles={{ words: { opacity: 0 } }}
  viewport={{ amount: 0.5, once: true }}
  onViewportEnter={({ words }) => animate(words, { opacity: 1 })}
>
  <p>Only animates once</p>
</SplitText>

Viewport Options

Usage tip: To run leave callbacks at the same threshold as enter, set viewport.leave to match viewport.amount and animate in onViewportLeave. Keep resetOnViewportLeave for instant resets once fully out of view.

Initial Styles

Use initialStyles to define start states declaratively, without setup loops in onSplit. Style values support normal CSS values and CSS custom properties.

<SplitText
  options={{ type: "words" }}
  initialStyles={{
    words: {
      opacity: 0,
      filter: "blur(8px)",
      transform: "translateY(20px)",
    },
  }}
  onSplit={({ words }) =>
    animate(words, { opacity: 1, filter: "blur(0px)", y: 0 })
  }
>
  <h1>Blur reveal effect</h1>
</SplitText>

You can also use a function for per-element customization:

<SplitText
  options={{ type: "chars" }}
  initialStyles={{
    chars: (el, index) => ({
      opacity: 0,
      transform: `translateY(${index * 2}px)`,
    }),
  }}
  onSplit={({ chars }) => animate(chars, { opacity: 1, y: 0 })}
>
  <h1>Staggered start positions</h1>
</SplitText>

Auto-Revert

Enable revertOnComplete and return an animation from the callback. Griffo restores original HTML when it finishes. Use onRevert to run follow-up logic.

<SplitText
  revertOnComplete
  onRevert={() => {
    console.log("SplitText reverted");
  }}
  onSplit={({ words }) => {
    return animate(words, { opacity: [0, 1] });
  }}
>
  <h1>Reverts after animation</h1>
</SplitText>

Masked Reveal

Use mask to wrap elements in a clipping container for reveal animations.

<SplitText
  options={{ type: "lines", mask: "lines" }}
  onSplit={({ lines }) => {
    animate(lines, { y: ["100%", "0%"] }, { delay: stagger(0.1) });
  }}
>
  <p>Each line reveals from below</p>
</SplitText>

Nested HTML Elements

Griffo preserves inline elements like <a>, <em>, and <strong>, including attributes (href, class, data-*, etc.).

Authored hard breaks are preserved automatically. Explicit <br> and block-level descendants are treated as hard boundaries; when splitting chars/words, boundaries are normalized to <br> in the split output.

<SplitText
  onSplit={({ chars }) => {
    animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });
  }}
>
  <p>
    Click <a href="/signup">here</a> to <em>get started</em>
  </p>
</SplitText>

With Ref (Scroll-Driven)

Pass a ref to SplitText to connect scroll-driven animations with Motion's scroll(). The ref points to the wrapper element.

import { useRef } from "react";
import { SplitText } from "griffo/react";
import { animate, scroll } from "motion";

function ScrollDrivenAnimation() {
  const targetRef = useRef<HTMLDivElement>(null);

  return (
    <SplitText
      ref={targetRef}
      options={{ type: "chars" }}
      onSplit={({ chars }) => {
        const target = targetRef.current;
        if (!target) return;

        const animation = animate(
          chars.map((char, i) => [
            char,
            { opacity: [0.2, 1] },
            { duration: 0.3, at: i * 0.025 },
          ]),
        );

        scroll(animation, {
          target,
          offset: ["start 85%", "start 20%"],
        });
      }}
    >
      <p>Each character reveals as you scroll</p>
    </SplitText>
  );
}