Getting Started

Legacy versions

Any release prior to 6.0.0 is considered legacy and is not compatible with version 6 or later. This documentation covers version 6.0.0 and above only. If you are on an older version, refer to the archived release notes for that version.

Installation

The package is published to both the npm registry and the GitHub Packages registry.

pnpm add eo-typewriterjs

To install from the GitHub Packages registry instead, scope the registry in your .npmrc:

@eoussama:registry=https://npm.pkg.github.com

Then install as usual:

pnpm add @eoussama/eo-typewriterjs

Quick start

In the browser (DOM renderer)

The DOM renderer writes directly into a target element. Each render call updates the element's innerHTML, so the output reacts to every step of the animation in real time.

import { createTypewriter, domRenderer } from "eo-typewriterjs";

const el = document.getElementById("output")!;

const tw = createTypewriter({
  renderer: domRenderer(el),
});

tw.timeline.type("Hello, World!");

await tw.play();

▼Live Preview

0ms / 0ms

Node.js / server (string renderer)

The string renderer accumulates output in memory instead of touching the DOM. Call renderer.toString() after playback to read the final text. This makes it usable in server-side rendering, test environments, and anywhere the browser document API is not available.

import { createTypewriter, stringRenderer } from "eo-typewriterjs";



const renderer = stringRenderer();

const tw = createTypewriter({ renderer });

tw.timeline.type("Hello, World!");

await tw.play();

console.log(renderer.toString()); // "Hello, World!"

▼Playback - string renderer writes to memory, not the DOM.

0ms / 0ms

Basic options

Control how text is typed with the by and interval options:

// Type word by word, 200 ms between each word
tw.timeline.type("The quick brown fox", {
  by: "word",
  interval: 200,
});

// Type 2 characters at a time, 50 ms apart
tw.timeline.type("Fast typing!", {
  by: { unit: "char", amount: 2 },
  interval: 50,
});

The default interval is 50 ms per step when interval is not specified.

Chaining commands

All timeline methods return this, so calls chain fluently:

tw.timeline
  .type("Line one.\n", { interval: 80 })
  .type("Line two.", { interval: 80 });

await tw.play(); // plays both in sequence

Note: The \n character is typed into the document as a literal newline. For it to render as a visible line break in the browser, the output element must preserve whitespace, for example by using a <pre> tag or adding white-space: pre via CSS.

Playback controls

tw.play() returns a Promise<void> that resolves when all events finish. The same instance also exposes pause, stop, and replay:

await tw.play();    // start - resolves on completion
tw.pause();         // pause at the current position
tw.stop();          // stop and reset to blank
await tw.replay();  // restart from the beginning
tw.cancel();        // stop and keep current output on screen

Inline callbacks

Use .call() to run code at any point in the animation:

tw.timeline
  .type("Building...", { by: "char", interval: 60 })
  .call(async ({ state }) => {
    console.log("text so far:", state.document.text);
    await doSomeWork();
  })
  .type(" Done!", { by: "char", interval: 60 });

await tw.play();

Async callbacks suspend playback until the returned promise settles.

Audio

Typing sounds are off by default. Pass audio: { enabled: true } to turn them on:

const tw = createTypewriter({
  renderer: domRenderer(el),
  audio: { enabled: true },
});

When no custom sfxs are provided the library automatically uses a built-in pack of keyboard-click samples. To reference or extend that pack explicitly, import it from the subpath entry:

import { DEFAULT_SFX_PACK } from "eo-typewriterjs/audio-pack";

The pack is code-split from the main bundle so it is only loaded when you import it.

You can adjust or toggle audio at any point during playback. Changes take effect immediately on the next sound event:

// Lower the volume mid-animation
tw.setAudioVolume(0.3);

// Mute audio entirely without stopping playback
tw.setAudioEnabled(false);

// Unmute and restore volume
tw.setAudioEnabled(true);
tw.setAudioVolume(1);

You can also replace the full audio configuration in one call:

tw.setAudioOptions({
  enabled: true,
  volume: 0.6,
});

Next steps

• Read the Core Concepts page to understand the document model, state shape, and how the pipeline works.
• See the Renderers guide for DOM, string, and custom renderer targets.
• Explore the Timeline page for all available commands and advance modes.
• Browse the Commands reference for per-command options, including type, delete, wait, move, select, style, and call.
• Try the interactive Sandbox to experiment with timelines in real time without any setup.