splitText()

Use splitText() to split DOM text into chars, words, and lines.

import { splitText } from 'griffo';

Parameters

element

HTMLElement — The DOM element containing text to split.

options

Prop	Type	Default
`type`	`SplitType`	`"chars,words,lines"`
`charClass`	`string`	`"split-char"`
`wordClass`	`string`	`"split-word"`
`lineClass`	`string`	`"split-line"`
`mask`	`MaskType`	—
`autoSplit`	`boolean`	`false`
`resplitDebounceMs`	`number`	`100`
`onResplit`	`(result) => void`	—
`onSplit`	`function`	—
`revertOnComplete`	`boolean`	`false`
`propIndex`	`boolean`	`false`
`disableKerning`	`boolean`	`false`
`initialStyles`	`object`	—
`initialClasses`	`object`	—

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

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

Return Value

interface SplitTextResult {
  chars: HTMLSpanElement[];   // Character elements
  words: HTMLSpanElement[];   // Word elements
  lines: HTMLSpanElement[];   // Line elements
  revert: () => void;         // Restore original HTML and cleanup
}

Font Loading

For stable kerning measurements, wait until fonts are loaded before splitting:

document.fonts.ready.then(() => {
  const { words } = splitText(element);
  animate(words, { opacity: [0, 1] });
});

The React and Motion components do this by default. Pass waitForFonts={false} to skip waiting.

Accessibility

Griffo keeps split text readable by screen readers. The accessibility strategy depends on element type.

Headings and Landmarks

For elements that support aria-label (headings, <section>, <nav>, etc.), Griffo adds aria-hidden="true" to split spans and sets aria-label on the parent:

<!-- Before -->
<h1>Hello World</h1>

<!-- After splitting -->
<h1 aria-label="Hello World">
  <span class="split-word" aria-hidden="true">Hello</span>
  <span class="split-word" aria-hidden="true">World</span>
</h1>

If the element already has an aria-label, Griffo preserves it.

Generic Elements and Nested Content

For elements like <span>, <div>, and <p> (which do not support aria-label), or when content includes inline elements like links/emphasis, Griffo hides the visual split output and adds a screen-reader-only copy:

<!-- Before -->
<p>Hello World</p>

<!-- After splitting -->
<p>
  <span aria-hidden="true" data-griffo-visual="true">
    <span class="split-word">Hello</span>
    <span class="split-word">World</span>
  </span>
  <span class="griffo-sr-only" data-griffo-sr-copy="true">
    Hello World
  </span>
</p>

The same approach works for nested inline content while preserving semantics for assistive technology:

<!-- Before -->
<p>Click <a href="/signup">here</a> to start</p>

<!-- After splitting -->
<p>
  <span aria-hidden="true" data-griffo-visual="true">
    <!-- Split visual content -->
  </span>
  <span class="griffo-sr-only" data-griffo-sr-copy="true">
    Click <a href="/signup">here</a> to start
  </span>
</p>

Authored hard breaks are preserved. Explicit <br> and block-level descendants become hard boundaries; in chars/words modes those boundaries are normalized to <br> in split output.

Examples

Basic Split

Split text and animate with any animation library.

import { splitText } from 'griffo';
import { animate } from 'motion';

const result = splitText(element);

animate(result.words, { opacity: [0, 1] });

With Auto-Revert

Use onSplit for the animation and revertOnComplete to restore original HTML when it finishes.

import { splitText } from 'griffo';
import { animate } from 'motion';

splitText(element, {
  onSplit: ({ words }) => animate(words, { opacity: [0, 1] }),
  revertOnComplete: true
});

Responsive Split

Enable autoSplit to re-split text on container resize. onResplit runs whenever a full resplit replaces split output.

If you use scroll-linked/scroll-triggered animation with autoSplit + lines, reattach that setup in onResplit so it binds to the new elements.

Call revert() when you no longer need the split.

import { splitText } from 'griffo';
import { animate } from 'motion';

splitText(element, {
  autoSplit: true,
  onResplit: ({ lines }) => {
    animate(lines, { opacity: [0, 1] });
  }
});

Masked Reveal

Use mask to wrap elements in a clipping container for reveal animations where content moves in from outside bounds.

import { splitText } from 'griffo';
import { animate, stagger } from 'motion';

splitText(element, {
  type: 'lines',
  mask: 'lines',
  onSplit: ({ lines }) => {
    animate(lines, { y: ['100%', '0%'] }, { delay: stagger(0.1) });
  }
});

Nested HTML Elements

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

import { splitText } from 'griffo';
import { animate, stagger } from 'motion';

// HTML: <p>Click <a href="/signup" class="link">here</a> to get started</p>
const { chars } = splitText(element);

// The <a> tag wraps the split characters, preserving href and class
animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });

With Initial Styles

Use initialStyles to set start states without looping. Styles are applied after split and kerning compensation.

import { splitText } from 'griffo';
import { animate, stagger } from 'motion';

splitText(element, {
  type: 'words',
  initialStyles: {
    words: { opacity: '0', transform: 'translateY(20px)' }
  },
  onSplit: ({ words }) => {
    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.05) });
  }
});

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

splitText(element, {
  type: 'chars',
  initialStyles: {
    chars: (el, index) => ({
      opacity: '0',
      transform: `translateY(${index * 2}px)`
    })
  }
});

With CSS Variables

Enable propIndex to add --char-index, --word-index, and --line-index CSS variables to each element.

splitText(element, { propIndex: true });

.split-char {
  animation-delay: calc(var(--char-index) * 0.05s);
}

For practical usage patterns, see the Vanilla examples.