AnimText is a JavaScript library for letter, word, & line animations. Easily create dynamic text effects with simple HTML data attributes.
npm install animtext
`
AnimText will automatically run on DOMContentLoaded — no manual init needed in most cases.
Animation Classes Powered by {css}animation
AnimText is designed to work hand-in-hand with the animation classes from {css}animation. These CSS classes are required to make the AnimText actually animate elements, so be sure to include them in your project.
Install the animation library:
`bash
npm install @hellouxpavel/cssanimation
`
Then import it in your JavaScript:
`js
import "@hellouxpavel/cssanimation";
`
Or include it via CDN:
`html
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@hellouxpavel/cssanimation@latest/dist/cssanimation.min.css" />
`
Without the cssanimation classes, AnimText can still spilt the text, but no animation will play.
Getting Started
To start using AnimText, all you need is a simple HTML element with the right attributes.
`html
Hello AnimText!
`
What’s Happening Here
- class="cssanimation"
This class is required. It activates the AnimText and ensures the element is styled correctly.
It also enables animation styles from the {css}animation library.
- data-at-sequence="ca__fx-fadeIn"
This tells AnimText to animate the text letter by letter, using the ca__fx-fadeIn animation class.
Letters will appear one after another in sequence.
You can replace ca__fx-fadeIn with any animation class from the {css}animation library. For the animation class check this demo and copy simply.
Once this setup is in place, AnimText handles the rest!
Supported Attributes
Below is a quick reference table for all the data-at-* attributes you can use with AnimText:
| Attribute | Description |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| data-at-sequence | Animates letter-by-letter, in order from first to last. |
| data-at-random | Animates letters in a randomized order. |
| data-at-reverse | Animates letters in reverse order (last letter animates first). |
| data-at-word | Animates word-by-word, one word at a time. |
| data-at-line | Animates line-by-line, based on or \n or custom separators. |
| data-at-delay | Sets delay (in ms) before each unit starts animating. Accepts one or multiple values. |
| data-at-base-duration | Sets a default animation duration (in ms) for each unit. Overrides CSS or internal defaults. |
| data-at-separator | Optional. Use "dot" to split lines on periods (.). Default is or line breaks. |
---
$3
`html
class="cssanimation"
data-at-word="ca__fx-fadeIn ca__fx-fadeInLeft ca__fx-slinkyDrop ca__fx-jiggleTransform"
data-at-delay="200 300 400"
data-at-base-duration="1000">
Animate each word smoothly
`
In this example:
- Each word gets its own animation class (cycled or repeated).
- Words animate with delays of 200ms, 300ms, then 400ms (last delay repeats if more words).
- Each word’s animation lasts 1000ms, regardless of what's in your CSS.
This lets you easily create custom animation flows without writing JavaScript.
Letter-by-Letter Animation
You can animate text letter by letter using different animation orders.
Just add one of these attributes to your element:
$3
Use data-at-sequence to animate each letter one after another in order.
`html
Letters Animate
`
$3
Use data-at-random to animate the letters in a shuffled, randomized order.
`html
Randomized entry!
`
$3
Use data-at-reverse to animate the last letter first, moving backward to the start.
`html
Backwards Flow
`
đź’ˇ You can customize the animation effect by replacing the class (e.g. ca__fx-fadeIn) with any animation class from {css}animation}.
Word-by-Word Animation
To animate each word in your text individually, use the data-at-word attribute:
`html
Each word animates uniquely
`
In this example, all the words will animate one by one using the ca__fx-fadeIn animation class.
In this example:
- Each word will animate one after another.
- All words use the same animation class: ca__fx-fadeIn.
đź’ˇ You can assign multiple animation classes or delay values if you want each word to behave differently. See Multiple Animation Classes for more.
Line-by-Line Animation
To animate each line of text separately, use the data-at-line attribute:
`html
First line
Second line
Third line
`
By default, AnimText splits lines using tags or actual line breaks (\n) .
Splitting by Periods (Dot Separator) You can also split text into lines using periods( . ), to do that, just add data-at-separator="dot".
`html
Step 1. Step 2. Step 3.
`
Each sentence (ending in a .) will be treated as a separate line and animated one after another.
Notes
- You don’t need to set data-at-separator if you're using data-at-word or data-at-line attributes:
html
class="cssanimation"
data-at-word="ca__fx-fadeIn ca__fx-moveFromTop ca__fx-moveFromBottom ca__fx-moveFromRight">
Each word animates uniquely
`
In this case, each word will use a different animation in order:
- "Each" - animate with ca__fx-fadeIn
- "word" - animate with ca__fx-moveFromTop
- "animates" - animate with ca__fx-moveFromBottom
- "uniquely" - animate with ca__fx-moveFromRight
If there are more words than classes, the last class will automatically be reused for the remaining words.
#### Line Example
`html
class="cssanimation"
data-at-line="ca__fx-blurIn ca__fx-bounceFromTop ca__fx-bounceX">
First line
Second line
Third line
`
Here:
- "First line" - animate with ca__fx-blurIn
- "Second line" - animate with ca__fx-bounceFromTop
- "Third line" - animate with ca__fx-bounceX
đź’ˇ This lets you mix and match effects to make your animations feel more playful or dramatic.
Animation Delay
You can control the delay between each animated unit (letter, word, or line) using the data-at-delay attribute.
The values are in milliseconds (ms).
The data-at-delay attribute specifies the delay before each animated unit (letter, word, or line) begins its animation. The values are in milliseconds (ms).
#### Single Value
If you use a single value, that delay will apply to every unit equally.
`html
Each letter delays by 100ms
`
All letters will animate one after another, each with a 100ms delay.
#### Multiple Values:
You can also provide multiple delay values, separated by spaces.
Each value is used for the next unit in order. If you have more units than delays, the last delay value repeats.
`html
First word, then 200ms, then 400ms, then 400ms
`
This gives you full control over timing rhythm, such as staggered or pulsed animations.
---
đź’ˇ Tip
This pattern works with letters, words, and lines.
Example: data-at-delay="50 100 100" means:
- First unit → 50ms delay
- Next unit → 100ms
- Remaining units → 100ms
You can create subtle or dramatic timing effects just by changing the delay pattern.
Animation Base Duration
The data-at-base-duration attribute lets you set a default animation duration (in milliseconds) for all animated units — whether they’re letters, words, or lines.
This value overrides any duration found in your CSS animation classes.
`html
class="cssanimation"
data-at-sequence="ca__fx-fadeIn"
data-at-base-duration="750">
Global base duration
`
In this example, all letters will animate with a base duration of 750ms - no need to set animation-duration in CSS.
How Duration is Chosen (Precedence)
1. data-at-base-duration (your manual override)
2. CSS-defined duration (auto-detected from your animation class if data-at-base-duration is absent)
3. Internal default (fallback if nothing is defined - usually 1000ms)
This means data-at-base-duration gives you full control: you can set durations directly in HTML without modifying your CSS.
Developer Tips
- The .cssanimation class is required for AnimText to work, it activates the logic and provides default styles.
- You can assign fewer animation classes or delay values than total units, the last value will repeat for the rest.
- If you assign more classes or delay values than units, the extra values are ignored, and a warning is logged to your console to help with debugging.
- All values (delays, durations) are parsed safely — invalid numbers are ignored and fall back to safe defaults.
- Duration logic follows this order:
- data-at-base-duration
- CSS-detected animation-duration
- Internal default (1000ms)
This setup makes AnimText flexible for both quick prototypes and polished production use.
Debugging AnimText
AnimText includes a simple debug mode that logs useful info to the browser console.
Enable Debug Mode
Set the following in your browser console or JavaScript file:
`js
window.__ANIMTEXT_DEBUG = true;
`
This will show:
- Which elements are being processed
- What attributes were parsed
- Fallback warnings (e.g. invalid delay values)
Re-Init on Dynamic Content
If you inject new elements after page load, call:
`js
animtext.init();
`
This will scan the DOM again and animate any new .cssanimation elements.
Test Example
Put this in your index.html:
`html
AnimText Test
rel="stylesheet"
href="node_modules/@hellouxpavel/cssanimation/dist/cssanimation.css" />
Hello AnimText!
``