text-animate-easy

v1.0.1

Published

2 months ago

Declarative text animations for the browser, using an [HTMX](https://htmx.org/)-style attribute syntax. Add a `text-animate` attribute to any element — no JavaScript required.

0High
0Medium
0Low

soniyaghale

text-animate

Declarative text animations for the browser, using an HTMX-style attribute syntax. Add a text-animate attribute to any element — no JavaScript required.

What it does

Animates text inside HTML elements. Supports typewriter, glow, aurora, and spotlight effects, with optional looping, viewport-triggered playback, and deep inheritance.

The library auto-discovers [text-animate] elements on page load and watches for new ones added to the DOM (e.g. after an HTMX swap).

How to use in your project

No build step required. Pick whichever method fits your setup.

Method 1: Script tag (plain HTML)

Best for static sites, no npm or bundler needed.

Step 1 — Get the file

Download dist/index.global.js from GitHub and place it in your project (e.g. js/text-animate.js).

Or, once published to npm, load it from a CDN:

<script src="https://unpkg.com/[email protected]/dist/index.global.js"></script>

Step 2 — Add the script to your HTML

<!DOCTYPE html>
<html>
<head>
  <title>My page</title>
</head>
<body>

  <script src="./js/text-animate.js"></script>

  <h1 text-animate="typewriter speed:30ms">Hello, world!</h1>
  <p text-animate="glow color:#fff glow-color:#0ff duration:1s">Glowing text</p>

</body>
</html>

That's it. The library auto-starts on page load.

Method 2: npm install (Vite, React, etc.)

Best when your project already uses a bundler.

Step 1 — Install

npm install text-animate

Step 2 — Import once in your entry file

// main.js, index.js, or app entry
import 'text-animate';

Step 3 — Use attributes in your HTML/JSX

<div text-animate="typewriter loop speed:12ms wait:1s viewport">
  Scroll down to see me type!
</div>

// React example
function App() {
  return (
    <h1 text-animate="glow color:#fff glow-color:#ff00aa intensity:30 duration:2s">
      Glowing headline
    </h1>
  );
}

Import text-animate once anywhere in your app. After that, any element with a text-animate attribute will animate automatically — including elements added later (e.g. after an HTMX swap).

Which method should I use?

| Your project | Use | |--------------|-----| | Plain HTML / no build tools | Script tag — download index.global.js | | Vite, React, Vue, Svelte, etc. | npm install text-animate + import 'text-animate' | | Want a CDN link, no download | <script src="https://unpkg.com/text-animate/dist/index.global.js"> |

Syntax

Like HTMX, everything is configured through a single HTML attribute with space-separated tokens:

<element text-animate="effect modifier modifier:value">

Modifiers

Modifiers are split into shared (work on any effect) and effect-specific.

Shared

| Token | Meaning | |-------|---------| | wait:1s | Wait before the animation starts | | pause:800ms | Hold between loop cycles | | loop | Repeat the animation | | viewport | Start when scrolled into view; pause when scrolled away | | deep | Apply the animation to child elements too |

Typewriter

| Token | Meaning | |-------|---------| | typewriter | Effect name | | speed:50ms | Time between each character (default 50ms) | | backward | Erase text after typing (use with loop) |

Glow

| Token | Meaning | |-------|---------| | glow | Effect name | | duration:2s | How long the glow fades in/out (default 800ms) | | color:#fff | Text color | | glow-color:#0ff | Glow color (default #00e5ff) | | intensity:20 | Glow strength in px (default 20) |

Aurora

| Token | Meaning | |-------|---------| | aurora | Effect name — flowing gradient colors inside text | | duration:4s | How long one color cycle takes (default 4s) | | aurora-colors:#00ff87,#60efff,#0061ff | Comma-separated gradient colors | | intensity:200 | Gradient spread in % — higher = wider color bands (default 200) | | color:#fff | Shortcut — sets the first gradient color |

Spotlight

| Token | Meaning | |-------|---------| | spotlight | Effect name — a bright beam sweeps across text | | duration:3s | How long one sweep takes (default 3s) | | color:#3a3a3a | Base text color (default #3a3a3a) | | spotlight-color:#fff | Beam highlight color (default #ffffff) | | intensity:15 | Beam width — higher = wider spotlight (default 15) |

Time values accept ms, s, or m (e.g. speed:12ms, wait:1s, duration:2s).

Examples

Basic typewriter:

<p text-animate="typewriter">This text types itself.</p>

Loop with custom speed:

<p text-animate="typewriter loop speed:30ms pause:2s">Looping text!</p>

Start when visible:

<div text-animate="typewriter viewport wait:500ms">
  I animate when you scroll to me.
</div>

Nested elements — child inherits and overrides:

<div text-animate="typewriter loop pause:3s speed:12ms wait:1s viewport deep">
  Parent text types first.

  <p text-animate="speed:22ms wait:10s viewport">
    Child inherits typewriter, but uses its own speed and wait.
  </p>
</div>

A child with only modifiers (no effect name) inherits the parent's effect. Any modifier on the child overrides the parent's value for that key.

Glow with custom colors:

<h1 text-animate="glow color:#fff glow-color:#ff00aa intensity:30 duration:2s viewport">
  Glowing headline
</h1>

Pulsing glow loop:

<p text-animate="glow loop color:#e0e0e0 glow-color:#00e5ff intensity:25 duration:1.5s pause:2s viewport">
  Soft pulsing glow
</p>

Nested glow inheritance:

<div text-animate="glow deep color:#fff glow-color:#0ff intensity:20 duration:1s viewport">
  Parent glows cyan.

  <span text-animate="glow-color:#f0f intensity:40 duration:2s">
    Child inherits glow, overrides color and intensity.
  </span>
</div>

Aurora gradient inside text:

<h1 text-animate="aurora duration:5s viewport">
  Northern lights in text
</h1>

Custom aurora palette:

<p text-animate="aurora aurora-colors:#ff00aa,#00ff87,#60efff,#7c3aed duration:3s intensity:250">
  Custom aurora colors
</p>

Nested aurora inheritance:

<div text-animate="aurora deep duration:4s viewport">
  Parent aurora text.

  <span text-animate="aurora-colors:#f0f,#0ff,#00f duration:2s">
    Child inherits aurora, overrides colors and speed.
  </span>
</div>

Spotlight sweep:

<h1 text-animate="spotlight color:#444 spotlight-color:#fff duration:3s viewport">
  Shine a light on this text
</h1>

Custom spotlight beam:

<p text-animate="spotlight color:#1a1a2e spotlight-color:#e94560 intensity:25 duration:2s loop">
  Wide pink spotlight sweep
</p>

Nested spotlight inheritance:

<div text-animate="spotlight deep duration:3s viewport">
  Parent spotlight.

  <span text-animate="spotlight-color:#0ff intensity:20 duration:1.5s">
    Child inherits spotlight, overrides beam color and speed.
  </span>
</div>

Development

For contributors working on this repo:

git clone https://github.com/sonya-ghale/text-animate.git
cd text-animate
npm install
npm run build    # build dist/
npm run typecheck