T-Writer.js


Native typewriter effect, without compromises or dependencies.

This is a fork of the original project from Christopher Cavalea with updated
dependencies, build scripts and Typescript type declarations.

See a demo for ideas/examples.

Why

Creating a custom typewriter effect can be cumbersome and time consuming. However, most of the libraries out there are either slow, bloated with dependencies, or lacking in functionality.

T-Writer.js was designed to provide maximum flexibility and usability, while remaining fast and dependency free.

Usage

Follow these steps to get started:

1. Install
2. Import
3. Instanciate
4. Overview
6. Review Api
5. Review Options

$3

Using NPM, install T-Writer and save it to your package.json dependencies.

``bash
$ npm install @philio/t-writer.js --save
`

$3

Import T-Writer, naming it according to your preference.

`es6
import Typewriter from '@philio/t-writer.js'
`

$3

Make as many instances of the Typewriter class as you would like. Upon instantiation, pass in the target element that will contain the typewriter, as well as an options hash.

`es6
// target element

const target = document.querySelector('.tw')

const options = {
loop: true
}

const writer = new Typewriter(target, options)
`

$3

To create a typewriter effect with T-Writer, you need to:

1. queue up actions
2. call the start() method

To queue up actions, use one of the queue methods in the API reference below. You can chain methods together to keep code DRY. See the demo for examples.

Every action returns a promise, guaranteeing that only one action is running at a time. This improves performance, since it eliminates the need to contantly check whether to continue to the next action.

The order of actions is preserved. Simply call start() again to repeat the effect. To clear the queue (effectively wiping the slate clean), use the clearQueue method.

API

Queue Methods:
* type
* remove
* rest
* strings
* clear
* then
* queueClearText
* changeOps
* removeCursor
* addCursor
* changeTypeColor
* changeCursorColor
* changeTypeClass
* changeCursorClass

Other:
* start
* clearText
* clearQueue

$3

* str -> string

Types the string given as an argument.

$3

* num -> integer

Removes the number of characters given as an argument.

$3

* interval -> integer
* amount of time, in milliseconds

Pauses the writer for the specified period of time.

$3

* interval -> integer
* amount of time, in milliseconds
* string1 -> string
* a string to be typed out

The writer will type out the first string, then rest for interval amount of time, then type the next string.

$3

Clear out the writer by deleting each character.

This differs from clearText and queueClearText. clear will delete characters one by one, according to the deleteSpeed specified.

$3

* callback -> function

Invoke the specified callback.

$3

Will queue the clearText action. This differs from clearText and clear. queueClearText will clear the text of the writer instantly, at the specified point in the queue.

queueClearText is the only way to clear the text of the writer instantly while it is running/looping.

$3

* options -> object

Will change the writer's options at the specified point in the queue. These options will persist for all further runs/loops of this particular instance.

$3

Queues a removeCursor action, which will remove the cursor until the next loop.

$3

Queues an addCursor action, which will add the cursor back.

Note: if using the animateCursor: 'none' option, addCursor will not take effect.

$3

* color -> string
* any css color

Changes the color of the typed portion of the writer.

$3

* color -> string
* any css color

Changes the color of the cursor.

$3

* className -> string

Changes the class attribute on the element that wraps around the text of the writer.

$3

* className -> string

Changes the class attribute on the element that wraps around the cursor.

$3

Starts the effect. The writer will go through it's queue of actions.

$3

Clears all text from the writer instantly. This is not a queued action, therefore, it can only be called once the writer has stopped running.

Since this is not a queued action, clearText will never run if the loop option is set to true. Use queueClearText if you wish to clear the writer during a loop.

$3

Clears the writer's queue, as well as all text in the writer. This is not a queued action, therefore, it will never run if the loop option is set to true.

Options

It is not required to pass in options, as each option comes with a default:

`es6
const defaultOptions = {
loop: false,
animateCursor: true,

blinkSpeed: 400,

typeSpeed: 90,
deleteSpeed: 40,

typeSpeedMin: 65,
typeSpeedMax: 115,

deleteSpeedMin: 40,
deleteSpeedMax: 90,

typeClass: 'type-span',
cursorClass: 'cursor-span',

typeColor: 'black',
cursorColor: 'black'
}
`

Explanation of each option follows:

general
* loop
* animateCursor
speeds
* blinkSpeed
* typeSpeed
* deleteSpeed
* typeSpeedMin
* typeSpeedMax
* deleteSpeedMin
* deleteSpeedMax
classes
* typeClass
* cursorClass
colors
* typeColor
* cursorColor

$3

Accepts a boolean.

* true -> the writer will loop through it's actions on repeat
* false -> the writer will run just one time

$3

Accepts either a boolean, or a string of "none".

* boolean
* true -> cursor blinks (according to blinkSpeed)
* false -> cursor does not blink

* string
* "none" -> cursor is not added

$3

Accepts an integer.

The time between each blink, given in milliseconds. A lower integer results in a faster blink speed.

$3

Accepts either an integer, or a string of "random".

* integer
* The time between typing a letter and typing the next, given in milliseconds. A lower integer results in a faster type speed.
* string
* "random" -> constantly re-evaluates the speed based on the typeSpeedMin and typeSpeedMax. Used for a more 'human' typing effect.

$3

Accepts either an integer, or a string of "random".

* integer
* The time between deleting a letter and deleting the next, given in milliseconds. A lower integer results in a faster delete speed.
* string
* "random" -> constantly re-evaluates the speed based on the deleteSpeedMin and deleteSpeedMax. Used for a more 'human' typing effect.

$3

Accepts an integer.

The minimum type speed, applicable only if using typeSpeed: "random".

$3

Accepts an integer.

The maximum type speed, applicable only if using typeSpeed: "random".

$3

Accepts an integer.

The minimum delete speed, applicable only if using deleteSpeed: "random".

$3

Accepts an integer.

The maximum delete speed, applicable only if using deleteSpeed: "random".

$3

Accepts a string.

The class given to the element that wraps around the typed portion of the writer. Use this option to specifically style the text of the writer.

$3

Accepts a string.

The class given to the element that wraps around the cursor portion of the writer. Use this option to specifically style the cursor of the writer.

$3

Accepts a string of any CSS color (rbg, 'white', etc).

Applies an inline-style to the element that wraps around the text portion of the writer.

$3

Accepts a string of any CSS color (rbg, 'white', etc).

Applies an inline-style to the ` element that wraps around the cursor portion of the writer.

Browser Support

T-Writer depends on the following browser APIs:

* requestAnimationFrame
* promises

Consequently, it supports the following natively:

* Chrome 32+
* Firefox 29+
* Safari 8+
* Opera 19+
* IE 9+ with polyfill
* iOS Safari 8+
* Android Browser 4.4.4+

License

MIT.
© 2018 Christopher Cavalea
© 2024 Phil Bayfield