# Theatre.js — card for AI agents

Animation library with a visual timeline editor for motion graphics on the web: animate DOM, three.js/R3F scenes and any JS values.

Category: Web animation examples and effects (also: Animation and motion capture, Video references and motion backgrounds) · maker Theatre.js · checked 2026-11-05 · style: 3d, abstract

## Price
- Price: Free
- Free tier: Fully free (open source).

## License
Apache-2.0 (@theatre/core); AGPL-3.0 (@theatre/studio) — https://raw.githubusercontent.com/theatre-js/theatre/main/README.md

- commercial: **yes** (Commercial use OK)
  > Your use of Theatre.js is governed under the Apache License Version 2.0
  (https://raw.githubusercontent.com/theatre-js/theatre/main/README.md)
- attribution: **no** (No credit needed)
  > Your use of Theatre.js is governed under the Apache License Version 2.0
  (https://raw.githubusercontent.com/theatre-js/theatre/main/README.md)
- in app: **yes** (Can ship inside your app)
  > only includes `@theatre/core`, so only the Apache License applies.
  (https://raw.githubusercontent.com/theatre-js/theatre/main/README.md)
- redistribute: **conditions** (Pass the files on to your users only with conditions)
  > The studio (`@theatre/studio`) is released under the AGPL 3.0 License.
  (https://raw.githubusercontent.com/theatre-js/theatre/main/README.md)

## Rules to follow
- Ship only @theatre/core in production; @theatre/studio (AGPL) is for design time.
- If you ship or host the studio editor, AGPL obligations apply.

## Can an AI agent use it by itself?
**Yes** · package: Agent installs a package or loads it from a CDN

## How an agent gets files
- npm install @theatre/core (and @theatre/studio as a dev dependency for the editor); animation state is saved as JSON and loaded by core. (sign-in: none)
- Formats: js, json
- Not allowed: Studio is AGPL

## How to connect
- Package (npm/PyPI)
- npm: `npm install @theatre/core`
- Repository: https://github.com/theatre-js/theatre
- Website: https://www.theatrejs.com

## Notes
README: development temporarily moved to a private repo ahead of 1.0 (as reported); npm @theatre/core is 0.7.2.

## Numbers (AgentGid data)
- Gid Score: 44
- GitHub stars: 13,029
- Downloads last week: 41,410

## Lines to paste into your prompt or AGENTS.md

```
- Theatre.js (Web animation examples and effects, Animation and motion capture, Video references and motion backgrounds). Animation library with a visual timeline editor for motion graphics on the web: animate DOM, three.js/R3F scenes and any JS values. Price: free; commercial use OK; no credit needed; pass the files on to your users only with conditions. Style: 3d, abstract.
  Connect: npm @theatre/core.
  Get files: npm install @theatre/core (and @theatre/studio as a dev dependency for the editor); animation state is saved as JSON and loaded by core (js, json).
  Not allowed: Studio is AGPL
  Rule: Ship only @theatre/core in production; @theatre/studio (AGPL) is for design time.
  Rule: If you ship or host the studio editor, AGPL obligations apply.
  License: https://raw.githubusercontent.com/theatre-js/theatre/main/README.md (checked 2026-11-05; details: https://agentgid.com/assets/theatre-js/)
```

## Links
- AgentGid page: https://agentgid.com/assets/theatre-js/
- Is it free for commercial use? https://agentgid.com/assets/theatre-js/commercial-use/
- Source: https://www.theatrejs.com/
- Source: https://raw.githubusercontent.com/theatre-js/theatre/main/README.md
- Source: https://registry.npmjs.org/@theatre/core/latest


## Theatre.js: a visual timeline for web animation

Theatre.js is a free animation library for websites with a visual timeline editor, like a small video editing tool that runs on top of your own page. You set keyframes for a headline, a button or a 3D camera by dragging values, then save the result as a file. Your live site plays that file with the small player part, and the editor stays on your computer.

### Where to use it
- Intro animation on a landing page: Fade and slide a headline and button into view with exact timing you tune by eye, then ship only the small player with the saved animation.
- Camera moves in 3D scenes: Plan a camera fly-through, lights or material colors in a three.js or React Three Fiber scene on a timeline instead of guessing numbers in code.
- Small motion details: Fine-tune hover, press and success animations of buttons and icons, where a few milliseconds and a softer curve change the feel.
- Animation in time with music: Attach a music or voice track so the animation and the sound always play in sync, for product stories or event pages.
- Generative and interactive art: Drive any value in your code, such as a color, a noise amount or a particle count, from the timeline for art pieces and interactive visuals.
- Still frames and a calm version: Jump the animation to any moment to make preview stills, or show a finished still frame to people who turn off motion in their settings. (idea, not from the official pages)

### How to start
- Install the player and the editor; the editor is only for development.

```
npm install --save @theatre/core @theatre/studio
```

- Design the animation in the Studio, export it from the project menu as state.json, and load it in the player.

```
import { getProject } from '@theatre/core'
import projectState from './state.json'
// This will load the state from the `state.json` file
const project = getProject('My Project', { state: projectState })
```

- Before going live, keep the Studio out of the production build.

```
if (import.meta.env.DEV) {
  studio.initialize()
}
```


### License
The player part is under the Apache 2.0 license: free for paid products if you pass its license on with your app. The editor part is under the stricter AGPL license, so keep it out of the site you ship, as the makers advise.

### Good to know
- What the editor license means in practice: using the editor on your own computer while you design is fine. Your shipped site then contains only the player.
- If you ship or host the editor itself, for example as a tool for your users, the stricter license applies. Changed copies must offer their source code to those users.
- Animations you make in the editor are saved only in that browser until you export them as a file, so export before clearing data or switching computers.
- The last public release is 0.7.2 from May 2024; the makers moved work to a private place ahead of version 1.0 and say the license stays open.
- The simple start needs only an HTML page and a script tag, with no build tools.

Checked 2026-11-09 against: https://www.theatrejs.com, https://www.theatrejs.com/docs/latest, https://www.theatrejs.com/docs/latest/getting-started, https://www.theatrejs.com/docs/latest/getting-started/with-html-svg, https://www.theatrejs.com/docs/latest/getting-started/with-three-js, https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber, https://www.theatrejs.com/docs/latest/manual/projects, https://www.theatrejs.com/docs/latest/manual/Studio, https://www.theatrejs.com/docs/latest/manual/audio, https://www.theatrejs.com/docs/latest/api/core, https://www.theatrejs.com/docs/latest/releases, https://www.theatrejs.com/docs/latest/api/studio, https://www.theatrejs.com/docs/latest/manual/sequences, https://www.theatrejs.com/docs/latest/concepts, https://github.com/theatre-js/theatre/blob/main/README.md, https://github.com/theatre-js/theatre/blob/main/LICENSE, https://raw.githubusercontent.com/theatre-js/theatre/main/packages/studio/LICENSE, https://registry.npmjs.org/@theatre/core/0.7.2, https://registry.npmjs.org/@theatre/studio/0.7.2, https://registry.npmjs.org/@theatre/core, https://registry.npmjs.org/@theatre/r3f/latest, https://registry.npmjs.org/@theatre/browser-bundles

### Mistakes to avoid
- Don't: Calling studio.initialize() unconditionally, or loading core-and-studio.js on the live site → Do: if (import.meta.env.DEV) { studio.initialize() } with a bundler, or core-only.min.js with the browser bundles (The editor is AGPL and meant for design time; in 0.7.2 core-and-studio.js is about 2.6 MB against about 99 KB for core-only.min.js (our demo check).)
- Don't: Shipping the site after designing the animation in the Studio, without exporting → Do: Export state.json from the Studio and pass it: getProject('My Project', { state: projectState }) (Until exported, the animation lives only in the localStorage of the browser it was made in.)
- Don't: sheet.sequence.play() right after getProject() → Do: project.ready.then(() => sheet.sequence.play()) (The project loads its state first; the docs start playback only after project.ready.)
- Don't: npm install @theatre/core@latest @theatre/studio@0.6 (mixed versions) → Do: Pin every @theatre package to the same version, e.g. 0.7.2 (Each package depends on an exact @theatre/dataverse version.)
- Don't: @theatre/r3f 0.7 with an older three or @react-three/fiber → Do: three >= 0.155.0 and @react-three/fiber >= 8.13.6 (This was a breaking change in 0.7.0.)

### Questions
- Can I use Theatre.js in a paid product? Yes for what you ship: the final bundle contains only @theatre/core, which is Apache-2.0, so only the Apache License applies. Keep the Studio out of production.
- What exactly is AGPL about it? Only @theatre/studio, the editor you use to make animations. It is meant for design and development time, not for your live site.
- How do I remove the editor before going live? With the browser bundles, swap core-and-studio.js for core-only.min.js; with a bundler, do not import Studio in production builds and remove all studio.initialize() calls.
- Where are my animations stored? While the Studio is open, in the browser localStorage; export them as a JSON file and pass it to getProject so your site can play them.
- Does it work with three.js? Yes. It can animate the camera, lights, material colors and more in three.js, and there is an extension for React Three Fiber.

---
AgentGid's catalog is curated: every entry was checked against the maker's official pages (registry, repository, license and pricing pages) on the date shown; a license value shows the quote it stands on wherever AgentGid has one. Usage numbers come from AgentGid's own scan of public repositories set up for AI coding agents. Claims by makers are reported, not tested by AgentGid.
