Docs - SplitFX

Introduction

SplitFX is a JavaScript plugin that splits the text of HTML elements into individual units (characters and words) and animates them.

It comes with a wide range of built-in animations (e.g., fade, swing, flipX, etc.), with full control over timing, delays, staggering, and easing, SplitFX makes it easy to create engaging text animations.

Animate In and Out on Scroll, Load, Hover, or Click and even use your custom animations. With no dependencies, it's easy to use.

Installation

SplitFX can be added to your project using one of the following installation methods:

Using npm

Install SplitFX using npm or Yarn:

npm install @tanglat/splitfx
# or
yarn add  @tanglat/splitfx

Then import it into your project:

import SplitFX from " @tanglat/splitfx";

const textAnimator = new SplitFX({
    //...
});

Using CDN

SplitFX can be loaded directly from a CDN using either the UMD or ES module build:

UMD Build

Include the UMD build. This exposes SplitFX as a global variable:

<script src="https://cdn.jsdelivr.net/npm/@tanglat/splitfx@1/dist/umd/splitfx.min.js"></script>

<script>
    const textAnimator = new SplitFX({
        //...
    });
</script>

<script src=https://unpkg.com/@tanglat/splitfx@1/dist/umd/splitfx.min.js"></script>

<script>
    const textAnimator = new SplitFX({
        //...
    });
</script>

ES Module Build

Import the ES module build inside a type="module" script:

<script type="module">
    import SplitFX from "https://cdn.jsdelivr.net/npm/@tanglat/splitfx@1/dist/es/splitfx.min.js";

    const textAnimator = new SplitFX({
        //...
    });
</script>

<script type="module">
    import SplitFX from "https://unpkg.com/@tanglat/splitfx@1/dist/es/splitfx.min.js";

    const textAnimator = new SplitFX({
        //...
    });
</script>

Using Local Files

Download the latest SplitFX release from GitHub Releases and extract the archive. The compiled builds are located in the dist directory, where you can choose either the UMD or ES module build depending on your project.

UMD Build

Include the UMD build. This exposes SplitFX as a global variable:

<script src="path/to/splitfx/dist/umd/splitfx.min.js"></script>

<script>
    const textAnimator = new SplitFX({
        //...
    });
</script>

ES Module Build

Import the ES module build inside a type="module" script:

<script type="module">
    import SplitFX from "path/to/splitfx/dist/es/splitfx.min.js";

    const textAnimator = new SplitFX({
        //...
    });
</script>

Supported HTML Elements

You can split and animate the text of HTML elements that contain text content (e.g. h1-h6, p, span, div, a, label, button, etc), Void elements such as img, input, and video splitting them makes no sense.

Example:

<h2 class="element-to-animate">Animate Me Using SplitFX</h2>

You can also split and animate text even when the element contains nested elements:

<h2 class="element-to-animate">You can <span>animate element text</span> with <strong>nested</strong> elements</h2>

Spaces around nested elements must be placed outside the tags, not inside them. Like the example above.
The following is incorrect:

<h2 class="element-to-animate">You can<span> animate element text </span>with<strong> nested </strong>elements</h2>

The space directly after the opening tag and the space directly before the closing tag will be removed.

Initialize SplitFX

To start using SplitFX, initialize it by creating a new instance of the SplitFX class:

const textAnimator = new SplitFX(options);

options (Object) — An optional configuration object that controls how the text is split and animated.

Example:

const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeTop",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "forward",
        delay: 0
    },

    out: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "backward",
        delay: 0
    },

    tagName: "span"
});

Options Reference

The SplitFX constructor accepts an optional configuration object that allows you to control how the text is split and animated.

Let's look on list of all available options:

Option	Type	Default	Description
`in`	`object`	`{ mode: "chars", includeSpaces: true, animation: "fade", duration: 500, easing: "ease", stagger: 50, staggerDir: "forward", delay: 0 }`	Defines how the units animate in. A unit is each piece of text that SplitFX animates. When `mode: "chars"`, units are characters; when `"words"` units are words.
`in.mode`	`string`	`"chars"`	Specifies the text units to animate: `"chars"` or `"words"`.
`in.includeSpaces`	`boolean`	`true`	Whether to treat spaces as individual units and include them in the animation. Applies only in `"chars"` mode.
`in.animation`	`string`	`"fade"`	Name of the animation applied to each unit. See full list of built-in animations.
`in.duration`	`number`	`500`	Animation duration (in milliseconds).
`in.easing`	`string`	`"ease"`	Easing function that controls the animation timing. Uses the same syntax as CSS timing functions, e.g. `ease`, `linear`, `cubic-bezier()`, etc.
`in.stagger`	`number`	`50`	Delay between starting the animation of each unit (in milliseconds), creating a staggered effect.
`in.staggerDir`	`string`	`"forward"`	Direction of the stagger sequence: `"forward"`, `"backward"`, `"random"`, `"centerOut"`, `"edgesIn"`, `"alternate"`, `"reverseAternate"`, `"centerOutAlternate"`, `"edgesInAlternate"`.
`in.delay`	`number`	`0`	Initial delay before the animation starts (in milliseconds).
`out`	`object`	`in`	Defines how the units animate out. By default, all `out` options inherit the values from the corresponding `in` options.
`out.mode`	`string`	`in.mode`	Specifies the text units to animate: `"chars"` or `"words"`.
`out.includeSpaces`	`boolean`	`in.includeSpaces`	Whether to treat spaces as individual units and include them in the animation. Applies only in `"chars"` mode.
`out.animation`	`string`	`in.animation`	Name of the animation applied to each unit. See full list of built-in animations.
`out.duration`	`number`	`in.duration`	Animation duration (in milliseconds).
`out.easing`	`string`	`in.easing`	Easing function that controls the animation timing. Uses the same syntax as CSS timing functions, e.g. `ease`, `linear`, `cubic-bezier()`, etc.
`out.stagger`	`number`	`in.stagger`	Delay between starting the animation of each unit (in milliseconds), creating a staggered effect.
`out.staggerDir`	`string`	`in.staggerDir`	Direction of the stagger sequence: `"forward"`, `"backward"`, `"random"`, `"centerOut"`, `"edgesIn"`, `"alternate"`, `"reverseAternate"`, `"centerOutAlternate"`, `"edgesInAlternate"`.
`out.delay`	`number`	`in.delay`	Initial delay before the animation starts (in milliseconds).
`tagName`	`string`	`"span"`	HTML tag used to wrap each individual unit. Accepts `"span"`, or `"div"`.
`vars`	`object`	{}	An object that overrides the supported CSS variables for built-in animations on a specific `SplitFX` instance. See Customizing Built-in Animations for more information.

Built-in Animations

SplitFX includes a wide variety of built-in animations:

fade
fadeRight
fadeLeft
fadeTop
fadeBottom
fadeTopRight
fadeTopLeft
fadeBottomRight
fadeBottomLeft
fadeHalf
flipX
flipY
rotateRight
rotateLeft
rotateTopRight
rotateTopLeft
rotateBottomRight
rotateBottomLeft
zoomIn
zoomInRight
zoomInLeft
zoomInTop
zoomInBottom
zoomOut
zoomOutRight
zoomOutLeft
zoomOutTop
zoomOutBottom
fadeRotateRight
fadeRotateLeft
fadeRotateTop
fadeRotateBottom
fadeRotateTopRight
fadeRotateTopLeft
fadeRotateBottomRight
fadeRotateBottomLeft
wipeRight
wipeLeft
wipeTop
wipeBottom
wipeCenter
wipeCircle
stamp
typeWriter
scanReveal
scanHighlight
jump
shakeX
shakeY
bounce
flash
rubberBand
heartbeat
swing
wobble
blur

Animations differ by their initial state: some start hidden (e.g., fadeTop, rotateLeft), while others start visible (e.g., swing, shakeX).
The initial state is applied when an HTML element is prepared.

Customizing Built-in Animations

SplitFX lets you create fully custom animations for complete control over your text effects. For supported built-in animations, you can also override CSS variables to customize properties such as colors and movement distances.

CSS Variable	Default	Applies to	Description
`--sfx-distance`	`60px`	Used by movement-based animations such as `fadeRight`, `fadeRotateBottom`, `jump`, and others.	Controls the movement distance used by the animation. Accepts any valid CSS length (e.g. `20px`, `2em`, `50%`, ...).
`--sfx-accent-color`	`#3b82f6`	`scanReveal`, `scanHighlight`	Accent color used by the animation.
`--sfx-cursor-color`	`#000`	`typeWriter`	Color of the typing cursor.
`--sfx-cursor-width`	`0.025em`	`typeWriter`	Width of the typing cursor. Avoid percentage (`%`) values. Use an absolute CSS length (e.g. `px`, `em`, or `rem`) instead.

Set any of these in your CSS to override the defaults:

For example:

:root {
    --sfx-cursor-color: black; /* Make the typing cursor black */
    --sfx-accent-color: green;
    --sfx-distance: 30px;
}

/* Dark Mode */
:root.dark {
    --sfx-cursor-color: white; /* Make the typing cursor white */
    --sfx-accent-color: greenyellow;
}

You can also override supported variables for a specific SplitFX instance using the vars option. Any values you provide override the default CSS variable values, but only for that instance.

const textAnimator = new SplitFX({
    in: {
        animation: "jump",
        duration: 400,
        easing: "ease-out",
        stagger: 40,
        staggerDir: "random"
    },
    out: {
        mode: "words",
        duration: 0,
        stagger: 0
    },

    vars: {
        distance: "20px" // Only changes the animation for this instance.
    }
});

Variable names use the same naming as their corresponding CSS variables, but without the --sfx- prefix and in camelCase. For example, --sfx-distance becomes distance, and --sfx-cursor-color becomes cursorColor.

You can also pass CSS custom properties to the vars option. For example:

vars: {
    accentColor: "var(--project-accent-color)"
}

Core Methods

Use Core Methods when you want full control to manually prepare and animate HTML elements' text according to your custom logic.

prepare()

textAnimator.prepare(elements, options);

Instance method that prepares target HTML element(s) for text animation by splitting the text into units (chars and words) and applying the initial state.

The initial state is taken from the first keyframe of in.animation.

Animations differ by their initial state: some start hidden (e.g., fadeTop, rotateLeft), while others start visible (e.g., swing, shakeX).

Parameter	Type	Default	Description
`elements`	`HTMLElement \| HTMLElement[ ] \| NodeListOf<HTMLElement>`	-	The HTML element(s) to prepare. Can be an `HTMLElement`, an array of `HTMLElements`, or a `NodeList` of `HTMLElements`.
`options`	`Object`	{}	Configuration options.
`options.force`	`boolean`	`false`	When `true`, forces preparation even if the element has already been prepared. Useful when the element's innerHTML has changed and you need to prepare it again.

Example:

// Select the HTML element(s) you want to animate
const element = document.querySelector(".element-to-animate");

// Create a new SplitFX instance with your configuration options
const textAnimator = new SplitFX({...});

// Prepare the element(s) (text is split, initial state applied)
textAnimator.prepare(element);

animateIn()

// Basic usage
textAnimator.animateIn(element);

// Or provide .onfinish to trigger logic once the animation finishes:
textAnimator.animateIn(element)
.onfinish = (element) => {
    // console.log('Do something after the animation finishes for:', element);
};

Instance method that animates the text of a previously prepared HTML element using the specified in animation configuration defined when creating the SplitFX instance.
Returns an object containing an optional onfinish callback property, which will be called once the animation is completed successfully.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	A previously prepared HTML element whose text will be animated in.

Animate In Demo

<button id="animate-in-btn">Animate In</button>
<div id="element">Animate In Demo</div>

const animateInBtn = document.getElementById("animate-in-btn");

const element = document.getElementById("element");

// Create a new SplitFX instance with your configuration options
const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "random",
        delay: 0
    },
    
    out: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "random",
        delay: 0
    },

    tagName: "span"
});

// Prepare the element
textAnimator.prepare(element);

// Trigger animateIn on the previously prepared element when the button is clicked
animateInBtn.addEventListener("click", () => {
    textAnimator.animateIn(element);
});

animateOut()

// Basic usage
textAnimator.animateOut(element);

// Or provide .onfinish to trigger logic once the animation finishes:
textAnimator.animateOut(element)
.onfinish = (element) => {
    // console.log('Do something after the animation finishes for:', element);
};

Instance method that animates the text of a previously prepared HTML element in reverse (i.e., the out.animation plays in reverse, from the last frame to the first.) using the specified out animation configuration defined when creating the SplitFX instance.
Returns an object containing an optional onfinish callback property, which will be called once the animation is completed successfully.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	A previously prepared HTML element whose text will be animated out.

Animate Out Demo

<button id="animate-out-btn">Animate Out</button>
<div id="element">Animate Out Demo</div>

const animateOutBtn = document.getElementById("animate-out-btn");

const element = document.getElementById("element");

// Create a new SplitFX instance with your configuration options
const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "random",
        delay: 0
    },
    
    out: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "random",
        delay: 0
    },

    tagName: "span"
});

// Prepare the element
textAnimator.prepare(element);

// Trigger animateIn on the previously prepared element
textAnimator.animateIn(element);

// Trigger animateOut on the previously prepared element when the button is clicked
animateOutBtn.addEventListener("click", () => {
    textAnimator.animateOut(element);
});

Convenience Methods

Convenience methods are shortcuts built on top of the core methods. They make SplitFX easier to use.

animateOnScroll()

textAnimator.animateOnScroll(element, options);

Instance method that animates the text of HTML element(s) on scroll.
Calls prepare() on the element if it hasn't been prepared yet, then triggers animateIn() when the element enters the viewport and animateOut() when it leaves.
Uses IntersectionObserver to detect visibility changes.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	An HTML element whose text will be animated on scroll.
`options`	`Object`	{}	Configuration options.
`options.repeat`	`boolean`	`true`	When `true`, triggers `animateIn()`/`animateOut()` every time the element enters or leaves the viewport.
`options.observerOptions`	`IntersectionObserverInit`	`{}`	Object containing `IntersectionObserver` options such as `threshold`, `root`, or `rootMargin`.
`options.trigger`	`Element`	`element`(First argument)	By default, `element` entering/leaving the viewport triggers `animateIn()`/`animateOut()` on itself. Pass a different element here to use it as the trigger element instead. (e.g. The trigger element entering/leaving the viewport triggers `animateIn()` and `animateOut()` on the target element passed as the first argument.) Useful, for example, when you have a card and want to animate the card's title text when the entire card enters the viewport, rather than when just the title becomes visible. In that case, you can use it like this: `animateOnScroll(title, { trigger: card })`.

Animate Me on Scroll

<div id="scroll-wrapper"> <!-- The scroll container the element scrolls inside -->

    <div id="element">Animate Me on Scroll</div>

</div>

const scrollWrapper = document.getElementById("scroll-wrapper");

const element = document.getElementById("element");

const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: true,
        animation: "fadeBottom",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "alternate",
        delay: 0
    },

    out: {
        mode: "words",
        duration: 0,
        stagger: 0,
        delay: 0
    }

});

textAnimator.animateOnScroll(element, {repeat: true, observerOptions: {root: scrollWrapper, threshold: 1}});

animateOnLoad()

textAnimator.animateOnLoad(element);

Instance method that animates the text of an HTML element when the window finishes loading.
Calls prepare() on the element if it hasn't been prepared yet, then triggers animateIn() once the load event fires.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	An HTML element whose text will animated on load.

Example:

// Select the HTML element you want to animate
const element = document.getElementById("element");

const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: false,
        animation: "rotateTopRight",
        duration: 500,
        easing: "linear",
        stagger: 50,
        staggerDir: "alternate",
        delay: 0
    }

});

textAnimator.animateOnLoad(element);

animateOnHover()

textAnimator.animateOnHover(element, options);

Instance method that animates the text of an HTML element on hover.
Calls prepare() on the element if it hasn't been prepared yet, then triggers animateIn() on mouse enter and animateOut() on mouse leave.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	An HTML element whose text will be animated on hover.
`options`	`Object`	{}	Configuration options.
`options.trigger`	`Element`	`element` (First argument)	By default, hovering `element` triggers `animateIn()`/`animateOut()` on itself. Pass a different element here to use it as the trigger element instead. (e.g. Hovering this trigger element triggers `animateIn()` and `animateOut()` on the target element passed as the first argument.) Useful, for example, when you have a card and want to animate only the card's title text when the user hovers over the entire card. In that case, you can use it like this: `animateOnHover(title, card)`.

Hover to Animate

<div id="element">Hover to Animate</div>

const element = document.getElementById("element");

const textAnimator = new SplitFX({

    in: {
        mode: "chars",
        includeSpaces: true,
        animation: "swing",
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "edgesIn",
        delay: 0
    },
    
    out: {
        staggerDir: "centerOut"
    }

});

textAnimator.animateOnHover(element);

animateOnClick()

textAnimator.animateOnClick(element, options);

Instance method that animates the text of an HTML element on click.
Calls prepare() on the element if it hasn't been prepared yet, then triggers animateIn() when the element is clicked.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	An HTML element whose text will be animated on click.
`options`	`Object`	{}	Configuration options.
`options.trigger`	`Element`	`element` (First argument)	By default, clicking`element` triggers`animateIn()` on itself. Pass a different element here to use it as the trigger element instead. (e.g. Clicking this trigger element triggers`animateIn()` on the target element passed as the first argument.) Useful, for example, when you have a button that contains both an icon and a label, and you want to animate only the label text when the user clicks the button. In that case, you can use it like this: `animateOnClick(label, button)`.

Click to Animate

<div id="element">Click to Animate</div>

const element = document.getElementById("element");

const textAnimator = new SplitFX({

    in: {
        mode: "words",
        includeSpaces: true,
        animation: "wobble",
        duration: 1000,
        easing: "linear",
        stagger: 0,
        staggerDir: "forward",
        delay: 0
    }

});

textAnimator.animateOnClick(element);

animateSequence()

SplitFX.animateSequence(element, steps, options);

A static method that runs a sequence of text animations inside an HTML element.

Parameter	Type	Default	Description
`element`	`HTMLElement`	-	The HTML element where the content of each step is inserted, prepared, and animated in and out.
`steps`	`Array<Object>`	-	Array of steps, each step is an object with optional properties. See the example below
`options`	`Object`	{}	Configuration options.
`options.repeat`	`number \| string`	`"infinite"`	Number of times to repeat the full sequence. Use `"infinite"` to loop forever.

Steps prameter example:

[
    {
        content: "Welcome to the first step!", // The content inserted into the HTML element during this step.
        allowHTML: false, // If true, content is injected as raw HTML. Ensure content is sanitized if it contains user data to prevent XSS attacks.

        in: {
            mode: "chars",
            includeSpaces: true,
            animation: "fadeTop",
            duration: 700,
            easing: "ease",
            stagger: 50,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            mode: "chars",
            includeSpaces: true,
            animation: "fadeBottom",
            duration: 400,
            easing: "ease",
            stagger: 30,
            staggerDir: "backward",
            delay: 3000 // Delay before "out" content stays visible for this duration after animating in and before animating out.
        },
        tagName: "span"
    },
    {
        content: "Now you've reached the <span class='highlight'>second</span> step!", // The content inserted into the HTML element during this step.
        allowHTML: true, // If true, content is injected as raw HTML. Ensure content is sanitized if it contains user data to prevent XSS attacks.

        in: {
            mode: "chars",
            includeSpaces: true,
            animation: "rotateTopRight",
            duration: 500,
            easing: "ease",
            stagger: 50,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            staggerDir: "backward",
            delay: 3000 // Delay before "out" content stays visible for this duration after animating in and before animating out.
        }
    }
    // ...etc
]

For each step, the method:

Optionally update the element's content (if content option is provided)
Triggers prepare() if the element's content was updated
Triggers animateIn() and waits for it to complete
Triggers animateOut()

If no content is provided in a step, the current content is reused and only the animation methods are triggered.

By default, the content is inserted as plain text. To render HTML, set allowHTML to true.

When allowHTML is set to true, content is injected as raw HTML without sanitization. Sanitize untrusted content to prevent XSS attacks.

Once all steps are completed, the sequence can repeat based on the repeat parameter.

Demo without content changes:

Bring text to life with SplitFX

<div id="element">Bring text to life with SplitFX</div>

const element = document.getElementById("element");

SplitFX.animateSequence(element, [

    {
        in: {
            mode: "chars",
            includeSpaces: false,
            animation: "wobble",
            duration: 1000,
            easing: "linear",
            stagger: 100,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            duration: 0,
            stagger: 0,
            delay: 1000
        },
        tagName: "span"
    },
    {
        in: {
            mode: "chars",
            includeSpaces: false,
            animation: "jump",
            duration: 400,
            easing: "ease-out",
            stagger: 40,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            duration: 0,
            stagger: 0,
            delay: 1000
        },
        vars: {
            distance: "20px"
        }
    }
    // etc

],
{ repeat: "infinite" });

Demo with content changes:

```
<div id="element"></div>
```

#element .highlight-1 {
    background-color: #f3f1ff;
    padding: 2px 4px;
    border-radius: 4px
}

#element .highlight-2 {
    border-bottom: 3px solid #00357F
}

#element .highlight-3 {
    color: #00357F
}

const element = document.getElementById("element");

SplitFX.animateSequence(element, [
    // Start - Step 1
    {
        content: "Welcome to the <span class='highlight-1'>first</span> step!",
        allowHTML: true, // If true, content is injected as raw HTML. Ensure content is sanitized if it contains user data to prevent XSS attacks.

        in: {
            mode: "chars",
            includeSpaces: true,
            animation: "fadeTop",
            duration: 700,
            easing: "ease",
            stagger: 50,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            mode: "chars",
            includeSpaces: true,
            animation: "fadeBottom",
            duration: 400,
            easing: "ease",
            stagger: 30,
            staggerDir: "backward",
            delay: 2000
        },
        tagName: "span"
    },
    // End - Step 1

    // Start - Step 2
    {
        content: "Now you've reached the <span class='highlight-2'>second</span> step!",
        allowHTML: true, // If true, content is injected as raw HTML. Ensure content is sanitized if it contains user data to prevent XSS attacks.

        in: {
            mode: "chars",
            includeSpaces: true,
            animation: "rotateTopRight",
            duration: 500,
            easing: "ease",
            stagger: 50,
            staggerDir: "forward",
            delay: 0
        },
        out: {
            staggerDir: "backward",
            delay: 2000
        }
    },
    // End - Step 2

    // Start - Step 3
    {
        content: "You're now on the <span class='highlight-3'>third</span> step!",
        allowHTML: true, // If true, content is injected as raw HTML. Ensure content is sanitized if it contains user data to prevent XSS attacks.

        in: {
            mode: "chars",
            includeSpaces: true,
            animation: "fadeBottom",
            duration: 500,
            easing: "ease",
            stagger: 50,
            staggerDir: "alternate",
            delay: 0
        },
        out: {
            staggerDir: "random",
            delay: 2000
        }
    }
    // End - Step 3

    // ...etc
],
{ repeat: "infinite" });

If you use animateSequence() on SEO-critical elements, such as a hero heading, it is recommended to include the first step's content directly in the HTML element so that search engines can index it.
This ensures that important content remains visible for SEO purposes.

So the HTML for the demo above should be:

<div id="element">Welcome to the <span class='highlight-1'>first</span> step!</div>

Instead of:

<div id="element"></div>

Use Your Custom Animations

SplitFX gives you the flexibility to build and use your own animations, allowing you to go beyond the built-in animations (e.g., fade, swing, flipX, etc.) and create custom text effects tailored to your needs.

Follow the steps below to do that:

Create Your Custom Animation(s)

To create your own animation(s), you should define them using the Web Animations API keyframe format.

For example, here's a custom animation called myRotateRight:

[
    {
        // from
        visibility: 'hidden',
        opacity: 0,
        transform: 'rotate(90deg)',
    },
    {
        // to
        visibility: 'visible',
        opacity: 1,
        transform: 'rotate(0deg)',
    }
]

Register Your Custom Animation(s)

After creating your custom animation(s), you can register your custom animation(s) using the static method registerCustomAnimations().

SplitFX.registerCustomAnimations(customAnimations, options);

Parameter	Type	Default	Description
`customAnimations`	`Object.<string, Keyframe[ ]>`	-	An object containing custom animations where each key is the animation name and the value is the corresponding keyframes array.
`options`	`Object`	{}	Configuration options.
`options.override`	`boolean`	false	When `true`, existing animations with the same name will be replaced by the newly provided ones instead of throwing an error.

Example:

SplitFX.registerCustomAnimations({
    "myRotateRight": [
        {
            // from
            visibility: 'hidden',
            opacity: 0,
            transform: 'rotate(90deg)',
        },
        {
            // to
            visibility: 'visible',
            opacity: 1,
            transform: 'rotate(0deg)',
        }
    ]
    // You can add more animations here
    // ...
});

const textAnimator = new SplitFX({

    in: {
        animation: "myRotateRight", // Applying the "myRotateRight" custom animation here
        duration: 500,
        easing: "ease",
        stagger: 50,
        staggerDir: "forward"
    },

    out: {
        animation: "myRotateRight", // Or apply it here as well
        staggerDir: "backward"
    }
});

You must call SplitFX.registerCustomAnimations() before initializing SplitFX with any animation that references your custom animations.

Clear Custom Animations
```
SplitFX.clearCustomAnimations();
```
Clears all custom animations previously registered via registerCustomAnimations.
Also resets built-in animations if they have been overridden.

SplitFX via Custom HTML Attribute

Call the static method initAll():

SplitFX.initAll();

Add the [data-splitfx] attribute to any HTML element whose text you want to animate. SplitFX will automatically prepare and animate it based on the specified "event".
Supported events: "scroll", "load", "hover" and "click".

Configuration options can be provided through the [data-splitfx] attribute in JSON format.
If no options are specified, default values will be applied.

Scroll Event (Default)

When "event" is set to "scroll" or omitted, the animateOnScroll() method will be called on the HTML element.

In this case, in addition to the event, you can also provide additional options such as:

SplitFX options
animateOnScroll() parameters

Example:

<h2 data-splitfx='{
    "in": {
        "mode": "chars",
        "includeSpaces": true,
        "animation": "fadeRight",
        "duration": 500,
        "easing": "ease",
        "stagger": 50,
        "staggerDir": "forward",
        "delay": 0
    },
    "out": {
        "mode": "words",
        "duration": 0,
        "stagger": 0,
        "delay": 0
    },

    "event": "scroll",

    "animateOnScroll": {
        "repeat": true,
        "observerOptions": {
            "threshold": 0,
            "rootMargin": "0px 0px 0px 0px",
            "root": null
        },
        "trigger": "trigger-css-selector"
    }
}'>
    Animate Me on Scroll!
</h2>

If you specify animateOnScroll.trigger or animateOnScroll.observerOptions.root, the value must be null or a valid CSS selector string that targets an existing element.

Load Event

When "event" is set to "Load", the animateOnLoad() method will be called on the HTML element.

In this case, in addition to the event, you can also provide additional options such as:

SplitFX options

Example:

<h2 data-splitfx='{
    "in": {
        "mode": "chars",
        "includeSpaces": true,
        "animation": "zoomOutLeft",
        "duration": 500,
        "easing": "ease",
        "stagger": 50,
        "staggerDir": "forward",
        "delay": 0
    },

    "event": "load"
}'>
    Animate In on Window Load!
</h2>

Hover Event

When "event" is set to "hover", the animateOnHover() method will be called on the HTML element.

In this case, in addition to the event, you can also provide additional options such as:

SplitFX options
animateOnHover() parameters

Example:

<h2 data-splitfx='{
    "in": {
        "mode": "chars",
        "includeSpaces": true,
        "animation": "swing",
        "duration": 500,
        "easing": "ease",
        "stagger": 20,
        "staggerDir": "edgesIn",
        "delay": 0
    },
    "out": {
        "staggerDir": "centerOut"
    },

    "event": "hover",

    "animateOnHover": {
        "trigger": "trigger-css-selector"
    }
}'>
    Animate Me on Hover!
</h2>

If you specify the animateOnHover.trigger option, it must be null or a valid CSS selector string that targets an existing element.

Click Event

When "event" is set to "click", the animateOnClick() method will be called on the HTML element.

In this case, in addition to the event, you can also provide additional options such as:

SplitFX options
animateOnClick() parameters

Example:

<h2 data-splitfx='{
    "in": {
        "mode": "words",
        "includeSpaces": true,
        "animation": "wobble",
        "duration": 1000,
        "easing": "linear",
        "stagger": 0,
        "staggerDir": "forward",
        "delay": 0
    },

    "event": "click",

    "animateOnClick": {
        "trigger": "trigger-css-selector"
    }
}'>
    Animate Me on Click!
</h2>

If you specify the animateOnHover.trigger option, it must be null or a valid CSS selector string that targets an existing element.

Introduction

Installation

Using npm

Using CDN

UMD Build

ES Module Build

Using Local Files

UMD Build

ES Module Build

Supported HTML Elements

Initialize SplitFX

Options Reference

Built-in Animations

Customizing Built-in Animations

Core Methods

prepare()

animateIn()

animateOut()

Convenience Methods

animateOnScroll()

animateOnLoad()

animateOnHover()

animateOnClick()

animateSequence()

Steps prameter example:

Demo without content changes:

Demo with content changes:

Use Your Custom Animations

Create Your Custom Animation(s)

Register Your Custom Animation(s)

Clear Custom Animations

SplitFX via Custom HTML Attribute

Scroll Event (Default)

Load Event

Hover Event

Click Event