typo-animation

Small dependency-free text reveal animation library for the browser.

import { typoAnimation } from "typo-animation";

const controller = typoAnimation.show("Animated text", {
  root: document.querySelector("#preview")!,
  delay: 40,
  offset: 8,
  duration: 240
});

controller.promise.then(() => {
  console.log("done");
});

API

typoAnimation.show(text, {
  root,
  delay,
  offset,
  duration,
  easing
});

• root is required and must be an HTMLElement.
• delay is the time in milliseconds between symbol starts. Default: 40.
• offset is the initial upward offset in pixels. Default: 8.
• duration is each symbol animation duration in milliseconds. Default: 240.
• easing is a CSS easing string. Default: cubic-bezier(0.2, 0, 0, 1).

show returns a controller with promise, cancel(), finish(), and reset().

For incremental text editing, create a stateful instance:

const text = typoAnimation.create({
  root: document.querySelector("#preview")!,
  delay: 28,
  offset: 14,
  duration: 220
});

text.append("A");
text.insert(0, ">");
text.remove(1);
text.setText("Only changed symbols animate");

setText compares the current and next grapheme arrays. Existing matching symbols keep their DOM nodes, inserted symbols animate in, and removed symbols animate out before their nodes are deleted.

Layout Contract

The library inserts the full text into root before the first animation frame, then animates only opacity and transform. It does not set font, color, size, spacing, width, or height. Give the container its dimensions and typography in your own CSS.

#preview {
  width: 480px;
  height: 160px;
  overflow: hidden;
  font: 32px/1.3 system-ui;
}

Development

npm install
npm run dev
npm run test
npm run build

Package

The npm package ships only the generated dist files plus package metadata, README, and license.

npm run verify
npm run publish:dry
npm run publish:public

Release helpers are available when you want npm to bump the version first:

npm run release:patch
npm run release:minor
npm run release:major

Before the first publish, log in with npm login. The package name typo-animation was available when checked on April 19, 2026.

GitHub Release CI

Pushes to main run .github/workflows/release.yml. The workflow verifies the package, reads package.json version, and creates a GitHub Release with tag v<version>. Release assets include the npm tarball, a dist zip, and a package archive. If the release already exists, the workflow skips release creation; bump package.json version before the next release.