threlte logo

Getting Started

Theatre.js is a javascript animation library with a professional motion design toolset. It helps you create any animation, from cinematic scenes in 3D, to delightful UI interactions.


As with the rest of Threlte, @threlte/theatre provides an idiomatic yet transparent Svelte wrapper. The core concepts of @threlte/theatre are:

@threlte/theatre ComponentDescriptionCorresponding Theatre.js Concept(s)
<Project>Contains your project’s animation sheetsProject
<Sheet>Binds to an animation sheet that contains animation sequencesSheet
<Sequence>Binds to an animation sequence and contains the animated componentsSequence
<Studio>Enables the Theatre.js in-browser studio interface during developmentStudio
<SheetObject>Enables editing and animating its parent in the studio interfaceSheet Object
<Theatre>A helper component providing a project with a single sheet and a studioProject, Sheet, Studio

The @threlte/theatre documentation cross-references the Theatre.js documentation, allowing you to get a deeper understanding of the underlying concepts.


Theatre.js combines programming in your IDE with editing in a browser-based GUI. The core workflow looks something like this:

  1. Create your scene as usual, placing a <Project> and one or more <Sheets> in your <Canvas>.
  2. Identify the elements and props you wish to edit in the <Studio>, and place an <SheetObject> component around them, then use the slotted components <Sync>, <Declare> or <Transform> to add editable props.
  3. Edit props and animations of elements in the <Studio> in the browser; config state is autosaved to local storage.
  4. Export the updated state as a JSON file by selecting your project in the studio and clicking export (top-right corner).
  5. Import your scene’s state.json and use it in your <Project>’s config prop.


npm install @threlte/theatre @theatre/core @theatre/studio

Quick Start

To get started quickly, encapsulate your whole scene in the component <Theatre>.

The component <Theatre> provides a default <Project> and <Sheet> and implements <Studio>. For a more flexible structure please consider using <Project>, <Sheet> and <Studio> on their own.

<script lang="ts">
  import { Canvas } from '@threlte/core'
  import { Theatre } from '@threlte/theatre'
  import Scene from './Scene.svelte'

    <Scene />

In your Scene, add the component <SheetObject> as a parent of any component you’d wish to edit or animate. The component <SheetObject> provides the components <Sync>, <Declare> and <Transform> that allow you to manipulate properties in Theatre.js based on your Threlte markup.

The component <Transform> is a shortcut to add position, scale and rotation at once as well as mount handy <TransformControls> whenever the respective Sheet Object is selected in the studio.

<script lang="ts">
  import { T } from '@threlte/core'
  import { OrbitControls } from '@threlte/extras'
  import { SheetObject } from '@threlte/theatre'

  position={[0, 5, 10]}
  <OrbitControls target={{ y: 1.5 }} />

<!-- Box -->
      <T.BoxGeometry args={[1, 1, 1]} />
      <T.MeshStandardMaterial color="#b00d03">

You will now see the Theatre.js studio interface. Make yourself comfortable with the controls and if you haven’t done yet, please read the Theatre.js studio manual and keyboard shortcuts.