Getting started

Video Tutorial

This guide is a work in progress. In the meantime, we've recorded a video tutorial that should quickly get you started with Theatre.js

Click here if the video is not visible (opens new window)

Before we start

Theatre comes as npm packages, so we need a module bundler (opens new window) like webpack (opens new window) or esbuild (opens new window). CodeSandbox (opens new window) would also work when configured.

Install Theatre

See this step in the video tutorial

Theatre comes in two packages:

Let's add @theatre/core as a dependency.

Then add @theatre/studio as a dev dependency since we just need it during development.

Import Theatre

import {getProject} from "@theatre/core"
import studio from "@theatre/studio"

// initialize the studio so the editing tools will show up on the screen

Set up the scene

Next, we'll set up an Object, a Sheet, and a Project.

See this step in the video tutorial

Create a Project

Let's call core.getProject() which creates a new Project or returns it if it already exists.

// create a project
const proj = getProject(
  // the ID of the project is "My first project"
  "First project"

A Project in Theatre.js is like a save file, except that its state is initially stored in the browser's local storage. Later we'll learn how to export this save file to an actual file and put it in a git repo.

Create a Sheet

An animation in Theatre.js is scoped to a Sheet, which we'll create next.

// create a sheet
const sheet = proj.sheet(
  // Our sheet is identified as "Scene"

A Sheet is like a component in React, or a composition in After Effects. It contains a number of objects that are animated together.

We can learn more about Sheets later. For now, let's move on to creating our first object.

Create an Object

Let's create an Object and call it "First object".

// create an object
const obj = sheet.object(
  // The object's key is "Fist object"
  "First object",
  // These are the object's default values (and as we'll later learn, its props types)
    // we pick our first props's name to be "foo". It's default value is 0.
    // Theatre will determine that the type of this prop is a number
    foo: 0,
    // Second prop is a boolean called "bar", and it defaults to true.
    bar: true,
    // Last prop is a string
    baz: "A string",

By now we should be able to see our project and sheet and object show up in the outline.

Read the values in code

Learn this step from the video tutorial

A basic way to read the value of an Object's props is via object.value.

console.log( // prints a number
console.log( // prints a boolean
console.log(obj.value.baz) // prints a string

If you change these values in the UI, and then read object.value again, you will see the updated values.

Listening to changes in values

Learn this step from the video tutorial

There are a few ways to listen to changes in values. The easiest method object.onValuesChange() is probably the easiest.

// Calls the callback every time the values change
const unsubscribe = obj.onValuesChange(function callback(newValue) {
  console.log( // prints a number
  console.log( // prints a boolean
  console.log(newValue.baz) // prints a string

// stop listening to changes after 5 seconds:
setTimeout(unsubscribe, 5000)

Hooking up our object to HTML

Learn this step from the video tutorial

The object.onValuesChange() method allows us to connect our Objects to visual elements, like HTML elements, WebGL, or even IOT devices.

// assuming we have an html element with #box as its ID
const div = document.getElementById("box")
obj.onValuesChange((newValue) => {
  // will now set the horizontal position of the div = + "px"


Learn this step from the video tutorial

So far, we've set the values of each prop statically. In order to animate them, we should put them on a sequence.

Right click on the label of the prop "foo", and choose "Sequence."

To be continued

The rest of the guide is currently being written. In the meantime, check out the video tutorial (opens new window).


Note on CodeSandbox

If you're using CodeSandbox, make sure to create a sandbox.config.json file and enable Hard Reload on Change.

  "hardReloadOnChange": true,