OnTyper

A directive-based typewriter for interactive web experiences.

Overview

OnTyper lets you create dynamic typewriter effects with embedded commands (directives) that control behavior in real time.

• Control typing behavior using inline directives
• Define custom variables and functions
• Execute synchronous and asynchronous functions during typing
• Supports HTML tags

Installation & Usage

Installation

Browser

Include the script tag:

<script src="https://cdn.jsdelivr.net/gh/rezzvy/ontyper@1023a49/dist/ontyper.min.js"></script>

const typer = new OnTyper({ target: null });
// change null to node element

Node

Install via npm:

npm install ontyper

import OnTyper from "ontyper";

const typer = new OnTyper({ target: null });
// change null to node element

Usage

typer.setFn("askName", () => {
  typer.setVar("name", prompt("What is your name?"));
});

typer.write("Hello there![@delay:500] What is your name? [@run:askName] I see...[@delay:1000], so your name is [@speed:1000][@var:name]");

Examples

Running an async function

<p class="text"></p>

const typer = new OnTyper({ target: document.querySelector(".text") });

typer.setFn("fetchData", async () => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, 2000);
  });
});

typer.write("Fetching data... [@async:fetchData] Data has been fetched!");

Evaluated a function value

<p class="text"></p>

const typer = new OnTyper({ target: document.querySelector(".text") });

typer.setFn("sayHi", (name) => {
  return `Hello ${name}`;
});

typer.write("[@eval:sayHi(Rezzvy)]");

Create function alias

<p class="text"></p>

const typer = new OnTyper({ target: document.querySelector(".text") });

typer.setFn("alert", (msg) => {
  alert(msg);
});

typer.setFnAlias("print", "alert");

typer.write("Hold up! [@print:Stop there!]");

Documentation

new OnTyper(options)

Initializes a new OnTyper instance. It accepts a single configuration object.

Property	Type	Default	Description
target	HTMLElement	Required	The DOM element where the typing effect will be rendered.
speed	Number	25	The default typing speed in milliseconds per character.
onStart	Function	undefined	Callback executed when the typing effect begins.
onTyping	Function	undefined	Callback executed immediately after a token or character is rendered.
onFinish	Function	undefined	Callback executed when the entire text sequence completes.

API Reference

write(text)

Starts the typing effect with the provided string.

Parameter	Type	Description
text	String	The text containing characters, HTML tags, and directives to type out.

setVar(key, val)

Registers a variable that can be injected into the text.

Parameter	Type	Description
key	String	The unique identifier for the variable.
val	Any	The value to substitute when [@var:key] is called.

setFn(key, fn)

Registers a function that can be executed via directives.

Parameter	Type	Description
key	String	The unique identifier for the function.
fn	Function	The function to execute.

setFnAlias(key, functionName, type)

Creates an alias for a registered function, allowing you to use a custom directive name.

Parameter	Type	Default	Description
key	String	-	The custom directive name (cannot be a reserved directive).
functionName	String	-	The name of the previously registered function.
type	String	"run"	The execution type. Must be "run", "async", or "eval".

pause()

Pauses the current typing execution.

resume()

Resumes a paused typing execution.

skip()

Skips the typing effect, immediately evaluating all remaining directives and injecting the rest of the text into the DOM.

destroy(clearDom)

Destroys the current instance and clears internal timers.

Parameter	Type	Default	Description
clearDom	Boolean	true	If true, clears the innerHTML of the target element.

isOnlyDirectives(text)

Utility method to check if a provided string consists exclusively of directives.

Parameter	Type	Description
text	String	The text to check. Returns true or false.

Directive Commands

Directives are embedded inside the text using the [@directive:value] syntax.

Directive	Syntax	Description
speed	[@speed:ms]	Changes the typing speed to the specified milliseconds per character.
delay	[@delay:ms]	Pauses the typewriter for the specified milliseconds.
var	[@var:key]	Injects the value of a registered variable into the text.
run	[@run:fn(param)]	Synchronously executes a registered function. Accepts an optional parameter.
async	[@async:fn(param)]	Pauses typing until the registered asynchronous function resolves.
eval	[@eval:fn(param)]	Executes a function and injects its return value directly into the text.

The api Object

The api object provides read-only state information about the current typewriter instance. It is passed into lifecycle events (onStart, onTyping, onFinish) and can be accessed externally via typer.api.

Property	Type	Description
tokens	Array	The array of parsed characters, HTML tags, and directives.
tokenIndex	Number	The current index being processed within the tokens array.
progress	Object	Returns an object containing the current progress: { raw: 0.5, percent: "50%" }.

Behavior

Variable Value

You can't put another variable directive inside the variable parameter like this:

typer.setVar("name", "[@var:name]");

Any directive inside the var string will be unwrapped to avoid an infinite loop.

Reserved Alias

You can't set a function alias that is similar to any built-in directive syntax. It will throw an error:

// This will throw an error
typer.setFnAlias("speed", "mySpeedFunc");

Contributing

There's always room for improvement. Feel free to contribute!

Licensing

The project is licensed under MIT License. Check the license file for more details.