Theatre.js Grid Notes
Keyframe timeline engine and visual studio overlay for choreographing Three.js / React Three Fiber cameras, lights and DOM properties.
Install and prerequisites
npm install @theatre/core && npm install -D @theatre/studio@theatre/core@theatre/studioInstall @theatre/core (Apache-2.0) as a runtime dependency and @theatre/studio (AGPL-3.0) as a development-only dependency.
Framework setup
Production-safe sheet playback with dev-only Studio
Load exported state JSON into getProject() for production, and initialize @theatre/studio behind a process.env.NODE_ENV === 'development' dynamic import.
import { getProject, types } from "@theatre/core";
import projectState from "./theatre-state.json";
if (process.env.NODE_ENV === "development" && typeof window !== "undefined") {
void import("@theatre/studio").then((studio) => studio.default.initialize());
}
export const project = getProject("HeroScene", { state: projectState });
export const sheet = project.sheet("Main");
export const cameraRig = sheet.object("Camera", {
x: types.number(0, { range: [-10, 10] }),
y: types.number(2, { range: [0, 10] }),
opacity: types.number(1, { range: [0, 1] }),
});Gotchas for agents
AGPL-3.0 licence on @theatre/studio
@theatre/coreis Apache-2.0, but `@theatre/studio` is AGPL-3.0. Never import@theatre/studiounconditionally in production code: guard it behindprocess.env.NODE_ENV === "development"so bundlers strip it from production builds.Development pause and React 19 peer warnings
Public npm releases paused at
0.7.2(2024) while the team works on 1.0 privately. Expect peer-dependency warnings on React 19;@theatre/coreworks without React, whereas@theatre/r3fmay need version overrides.Wait for project.ready before playing sequences
Calling
sheet.sequence.play()beforeawait project.readyresolves silently fails to use the exported JSON state.
Accessibility and reduced motion
Reduced motion
When prefers-reduced-motion: reduce matches, skip sheet.sequence.play() and set sheet.sequence.position directly to the final keyframe timestamp (sheet.sequence.position = 2.5).
Keyboard and screen readers
In development, @theatre/studio mounts a fixed overlay that captures keyboard shortcuts (such as Space). Never ship Studio to end users, and provide a pause button if a sequence loops.
More Grid Notes
- LenisLightweight smooth-scroll engine that keeps native browser scrolling, sticky positioning and intersection observers intact, and pairs cleanly with GSAP ScrollTrigger.
- GSAPTimeline, scroll-linked and text-splitting animation engine. All plugins — including ScrollTrigger, SplitText and MorphSVG — are included under Webflow's no-charge licence.
- MotionMIT-licensed animation library for React and JavaScript (formerly Framer Motion), offering a 3.3 kB `motion/mini` WAAPI build as well as layout, gesture and spring animations.
- dotLottieLottieFiles' WebAssembly-powered player for `.lottie` archives and Lottie JSON animations, with official wrappers for React, Vue, Svelte and plain web canvas.
- NumberFlowDependency-free animated number component for React, Vue and Svelte that rolls individual digits into place and formats values with `Intl.NumberFormat`.
- RiveInteractive state-machine graphics packaged in compact `.riv` files and driven at 60–120 fps by Rive's open-source WebGL2 and Canvas runtimes.



