Theatre.js — Visual Animation Toolbox for the Web

Introduction

Theatre.js is an animation library that combines a programmatic API with a visual studio for designing motion. You define animatable properties in code, then use the in-browser timeline editor to keyframe, ease, and preview animations visually, bridging the gap between developer precision and designer-friendly tooling.

What Theatre.js Does

• Provides a visual timeline editor that runs in the browser during development
• Animates any JavaScript value including DOM properties, Three.js objects, and custom state
• Supports keyframe-based animation with customizable easing curves per property
• Exports animation state as JSON that plays back in production without the editor
• Integrates with React Three Fiber for animating 3D scenes visually

Architecture Overview

Theatre.js separates into two packages: @theatre/core (runtime) and @theatre/studio (editor). The core manages a project-sheet-object hierarchy where each object declares typed props. The studio provides a React-based UI with a timeline, curve editor, and outline panel that writes keyframe data into the project state. In production, only core loads and reads the exported JSON state file.

Self-Hosting & Configuration

• Install core and studio packages via npm in your project
• Initialize the studio in development and remove it for production builds
• Define animatable objects with typed props like types.number() and types.stringLiteral()
• Use the timeline UI to set keyframes, adjust curves, and sequence animations
• Export the state JSON and load it in production with getProject(name, { state })

Key Features

• In-browser visual editor with a professional-grade timeline and curve editor
• Type-safe prop definitions for numbers, booleans, strings, and compound types
• Sequence-based playback with position control, looping, and speed adjustment
• First-class React Three Fiber integration for 3D scene animation
• Production runtime under 5 KB gzipped with no editor overhead

Comparison with Similar Tools

• GSAP — Code-driven tweening engine; Theatre.js adds a visual editor workflow
• Framer Motion — Declarative React animations; Theatre.js offers timeline-based sequencing
• Rive — Binary animation format with a desktop editor; Theatre.js uses the browser as the editor
• Motion Canvas — Code-only animation for video export; Theatre.js is interactive and visual

FAQ

Q: Does Theatre.js add weight to production builds? A: No. The studio is dev-only. The production runtime is under 5 KB and only reads exported JSON.

Q: Can I animate CSS properties directly? A: Yes. Bind Theatre.js props to element styles in an onChange callback to animate any CSS value.

Q: How does the React Three Fiber integration work? A: The @theatre/r3f package provides a component that wraps R3F objects, exposing their transforms in the Theatre.js editor.

Q: Can multiple developers collaborate on animations? A: The exported state is a JSON file that can be committed to version control and merged like any other source file.

Sources

• https://github.com/theatre-js/theatre
• https://www.theatrejs.com