Helpers API

These helpers are built to make common split-text animation patterns easier to implement. This is a growing collection, and more utilities will be added over time.

import { createSplitClones } from "fetta/helpers";

createSplitClones()

Creates clone layers (and optional track wrappers) from split output. This is useful for reveal/swap effects without coupling to a specific animation library.

createSplitClones(
  split: SplitTextResult,
  options: CreateSplitClonesOptions
): CreateSplitClonesResult

Parameters

SplitTextResult

SplitTextResult from splitText().

CreateSplitClonesOptions

Prop	Type	Default
`unit`	`"chars" \| "words" \| "lines"`	—
`wrap`	`boolean`	`false`
`display`	`"auto" \| "inline-block" \| "block"`	`"auto"`
`cloneOffset.axis`	`"x" \| "y"`	`"y"`
`cloneOffset.direction`	`"start" \| "end"`	`"start"`
`cloneOffset.distance`	`string`	`"100%"`
`trackClassName`	`string \| (ctx) => string \| undefined`	—
`cloneClassName`	`string \| (ctx) => string \| undefined`	—
`trackStyle`	`object \| (ctx) => object`	—
`cloneStyle`	`object \| (ctx) => object`	—

Context callbacks receive:

{
index: number;
unit: "chars" | "words" | "lines";
original: HTMLSpanElement;
}

Return Value

interface CreateSplitClonesResult {
  unit: "chars" | "words" | "lines";
  originals: HTMLSpanElement[];
  clones: HTMLSpanElement[];
  tracks: HTMLSpanElement[];
  items: Array<{
    index: number;
    original: HTMLSpanElement;
    clone: HTMLSpanElement;
    track: HTMLSpanElement | null;
  }>;
  cleanup: (options?: { revertSplit?: boolean }) => void;
}

Behavior Notes

The helper does not call splitText(); pass an existing split result.
Clones are appended to each original node's current parent.
With wrap: false, clone is appended directly to the existing parent.
With wrap: true, each original is moved into a generated track wrapper first, then the clone is appended there.
cleanup() is idempotent and removes helper-created DOM.
cleanup({ revertSplit: true }) also calls split.revert().

For reveal/swap effects, pair this with matching mask in splitText() ("chars", "words", or "lines").

Examples

Basic Layered Setup

import { splitText } from "fetta";
import { createSplitClones } from "fetta/helpers";

const split = splitText(element, { type: "chars", mask: "chars" });

const layers = createSplitClones(split, {
  unit: "chars",
  wrap: true,
});

// Animate layers.tracks / layers.clones / layers.originals
// ...

layers.cleanup(); // remove tracks + clones, keep split DOM

Cleanup + Revert Split

import { splitText } from "fetta";
import { createSplitClones } from "fetta/helpers";

const split = splitText(element, { type: "lines", mask: "lines" });
const layers = createSplitClones(split, { unit: "lines", wrap: true });

// Later:
layers.cleanup({ revertSplit: true }); // also restores original unsplit DOM