# Theatre.js — Visual Animation Toolbox for the Web

> A JavaScript animation library with a visual editor that lets you design and fine-tune complex animations for DOM elements, Three.js scenes, and any JavaScript value with a professional timeline UI.

## Install

Save as a script file and run:

# Theatre.js — Visual Animation Toolbox for the Web

## Quick Use
```bash
npm install @theatre/core @theatre/studio
# In your app:
# import { getProject, types } from '@theatre/core';
# import studio from '@theatre/studio';
# studio.initialize();
# const project = getProject('My Project');
# const sheet = project.sheet('Scene');
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-794a1358
Author: Script Depot