Home

Awesome

TheaterJS

Typing animation mimicking human behavior.

If you're not particularly interested in managing multiple actors and the several features TheaterJS has to offer (e.g mistakes, variable speed, callbacks, html support, and so on), have a look at this fiddle. It's a minimalist version that supports play/stop, it has a lot of comments so you understand what's going on under the hood. It might well be enough for you usage :)

Installation

With npm:

npm install theaterjs

With yarn:

yarn add theaterjs

Example

<div id="vader"></div>
<div id="luke"></div>

<script src="path/to/theater.min.js"></script>
<script>
  var theater = theaterJS();

  theater
    .on("type:start, erase:start", function() {
      // add a class to actor's dom element when he starts typing/erasing
      var actor = theater.getCurrentActor();
      actor.$element.classList.add("is-typing");
    })
    .on("type:end, erase:end", function() {
      // and then remove it when he's done
      var actor = theater.getCurrentActor();
      actor.$element.classList.remove("is-typing");
    });

  theater.addActor("vader").addActor("luke");

  theater
    .addScene("vader:Luke...", 400)
    .addScene("luke:What?", 400)
    .addScene("vader:I am", 200, ".", 200, ".", 200, ". ")
    .addScene("Your father!")
    .addScene(theater.replay);
</script>

Documentation

To get started, you'll first need to create a new TheaterJS object by eventually providing some options.

Example

var theater = theaterJS({ locale: "fr" });

Usage

theaterJS(<options>)
ParamDefaultDescription
options{autoplay, locale, minSpeed, maxSpeed}Options (see below).

Breakdown of the available options:

OptionDefaultDescription
autoplaytrueIf true, automatically play the scenario (when calling addScene).
localedetectDetermine which keyboard to use when typing random characters (mistakes). Note: "detect" is an option to detect the user's locale and use if it's supported.
minSpeed{ erase: 80, type: 80 }Minimum delay between each typed characters (the lower, the faster).
maxSpeed{ erase: 450, type: 450 }The maximum delay between each typed characters (the greater, the slower).

Regarding minSpeed and maxSpeed, you can also just pass a number instead of an object. If you do so, this value will be used for both the erase and type speed, e.g:

{
  "minSpeed": {
    "erase": 80,
    "type": 80
  },

  "maxSpeed": {
    "erase": 450,
    "type": 450
  }
}

Is equivalent to:

{
  "minSpeed": 80,
  "maxSpeed": 450
}

TheaterJS objects have two public (read only) properties:

addActor

Add an actor to the casting.

Example

var theater = theaterJS();

theater
  .addActor("vader")
  .addActor("luke", 0.8, ".luke-selector")
  .addActor("yoda", { accuracy: 0.4, speed: 0.6 }, function(displayValue) {
    console.log("%s said yoda", displayValue);
  });

Usage

theater.addActor(<name>, <options>, <callback>)
ParamDefaultDescription
nameName used to identify the actor.
options0.8Actor's options (see below).
callback(see below)A function to call when actor's display value changes.

Actors have two options:

Note: the delay between each typed character varies to "mimick human behavior".

An actor callback is a function that is called when its display value is set. It can also be a string, in such case TheaterJS will assume it's a DOM selector and will look for the corresponding element. It's then going to set the element's innerHTML when the value changes. You can safely ignore this argument if you gave the target element an id with the name of the actor, i.e:

theater.addActor("vader");

In this situation, TheaterJS will look for an element that matches the selector #vader. Also note that the actor will have an additional $element property referring to the DOM element when using a selector string.

getCurrentActor

Return the actor that is currently playing.

Example

var theater = theaterJS();

theater
  .addActor("vader")
  .addScene("vader:Luke...")
  .addScene(function(done) {
    var vader = theater.getCurrentActor();
    vader.$element.classList.add("dying");
    done();
  });

Usage

theater.getCurrentActor();

addScene

Add scenes to the scenario and play it if options.autoplay is true.

Example

var theater = theaterJS();

theater
  .addActor("vader")
  .addScene("vader:Luke... ", "Listen to me!", 500)
  .addScene(theater.replay);

Usage

theater.addScene(<scene>)

A scene can be of 5 different types:

theater
  .addScene("vader:Luke... ") // 1
  .addScene(800) // 2
  .addScene("I am your father!") // 3
  .addScene(-7) // 4
  .addScene("mother!")
  .addScene(function(done) {
    // do stuff
    done();
  }); // 5
  1. .addScene('vader:Luke... ') erase actor's current display value, then type the new value.
  2. .addScene(800) make a break of 800 milliseconds before playing the next scene.
  3. .addScene('I am your father!') append value to the current actor's display value.
  4. .addScene(-7) erase 7 characters.
  5. .addScene(fn) call fn which receives a done callback as first argument (calling done() plays the next scene in the scenario).

Note that addScene actually accepts an infinite number of arguments so you could just do:

theater
  .addScene("vader:Luke... ", 800, "I am your father!")
  .addScene(-7, "mother!")
  .addScene(fn);

getCurrentSpeech

Return the speech that is currently playing.

Example

var theater = theaterJS();

theater
  .addActor("vader")
  .addScene("vader:Luke...")
  .on("type:start", function() {
    console.log(theater.getCurrentSpeech()); // outputs 'Luke...'
  });

Usage

theater.getCurrentSpeech();

play

Play the scenario.

Example

var theater = theaterJS({ autoplay: false });

theater.addActor("vader").addScene("vader:Luke...");

document.querySelector("button").addEventListener(
  "click",
  function() {
    theater.play();
  },
  false
);

Usage

theater.play();

replay

Replay the scenario from scratch (can be used as a callback to create a loop).

Example

var theater = theaterJS();

theater
  .addActor("vader")
  .addScene("vader:Luke...")
  .addScene(theater.replay);

Usage

theater.replay();

stop

Stop the scenario after the current playing scene ends.

Example

var theater = theaterJS();

theater.addActor("vader").addScene("vader:Luke... ", "I am your father...");

document.querySelector("button").addEventListener(
  "click",
  function() {
    theater.stop();
  },
  false
);

Usage

theater.stop();

on

Add a callback to execute when an event is emitted (e.g when a scene starts/ends).

Example

var theater = theaterJS();

theater
  .on("type:start, erase:start", function() {
    var actor = theater.getCurrentActor();
    actor.$element.classList.add("blinking-caret");
  })
  .on("type:end, erase:end", function() {
    var actor = theater.getCurrentActor();
    actor.$element.classList.remove("blinking-caret");
  });

theater.addActor("vader").addScene("vader:Luke...");

Usage

theater.on(<eventName>, <callback>)
ParamDefaultDescription
eventNameEvent's name to listen to.
callbackFunction to call when the event got published.

The callback function receives the event's name as first argument.

A couple of things to note:

Localized Keyboards

When making a mistake, an actor's gonna type a random character near the one he intended to. Those characters are taken from a "mapped" keyboard that you can configure on TheaterJS' instantiation: theaterJS({locale: 'en'}).

Change Log

3.2.0 - 2018-06-04

3.1.0 - 2016-11-14

3.0.0 - 2016-03-20

2.2.1 - 2016-03-19

2.2.0 - 2016-03-17

2.1.0 - 2016-03-15

2.0.2 - 2016-03-13

2.0.1 - 2015-11-02

2.0.0 - 2015-11-02