With React Three Fiber

In this guide, you'll learn how to animate a 3D scene by integrating Theatre.js into a @react-three/fiber project using the @theatre/r3f extension. For a plain Three.js guide, see Getting started with THREE.js.

While Theatre.js is library-agnostic, extensions help you more easily integrate it with other tools, frameworks, and libraries.

#Prerequisites

This guide assumes that you have a web project with a bundler set up. Don't have one? No problem, you can follow one of the popular bundler getting start guides: webpack, esbuild, Parcel, or Vite ( recommended).

Once you're set up, navigate to the folder containing the project in your terminal, and you're ready to get started.

#Installing dependencies

Run the commands below to install the dependencies we'll be using.

Want to use yarn?

# r3f and its deps

yarn add react three @react-three/fiber

# Theatre.js

yarn add @theatre/core@0.5 @theatre/studio@0.5 @theatre/r3f@0.5

# Three.js types (when using Typescript)

yarn add --dev @types/three

#R3F starter code

We will start with the following simple r3f code, and then we'll see how we can add Theatre.js to it.

To start, we'll create a main.tsx file containing the code in the code block below. For example, if you're using the vite react-ts starter, you can replace the entire contents of the main.tsx file with the following:

Once you've saved, ran your bundler, and opened the bundled webpage in your browser, you will see something like the following screenshot:

#Adding the Studio UI

Now, let's add Theatre.js Studio, the Theatre.js GUI that enables you to edit your scene and animations while developing your project.

Add the following lines below the other imports in main.tsx to initialize Theatre.js Studio.

You will now see the Studio appear on top of your webpage. However, the r3f extension is still missing. Let's add the extension by calling studio.extend:

You can call studio.extend as many times as you want, once for any extension you want to use. You can even make your own extension to extend Theatre.js's capabilities.

Tip: only include Theatre.js Studio in "development" builds

If your environment supports it, you can wrap the above code in an environment check to ensure you only include Studio in "development" builds of your webpage.

// Vite

if (import.meta.env.DEV) {

studio.initialize()

studio.extend(extension)

}

// create-react-app

if (process.env.NODE_ENV === 'development') {

studio.initialize()

studio.extend(extension)

}

After extending Theatre.js with the r3f extension, a new button will appear in the top left of the UI:

Clicking on it will bring up the scene editor, but the editor will contain an empty space because it is not connected to our scene yet.

We can connect our scene to the r3f extension by wrapping our r3f scene in a SheetProvider component, which will make the scene visible in the editor. Let's do that.

Add an import of SheetProvider from @theatre/r3f:

Then, add a wrapping <SheetProvider sheet={demoSheet}> with reference to the demoSheet from above:

Now, our little yellow cube will show up in Theatre.js' r3f snapshot editor:

#Making objects editable

While we can now see objects and move around the scene in the editor, we cannot edit the objects yet. We need to mark objects as editable for the r3f extension to be able to instrument their values.

To make an object editable, import editable as e from the extension.

Then prefix the object's JSX element with e., and add the theatreKey prop. The following code will make the point light object editable:

We can verify that the point light object is editable by opening the scene editor and

• click-dragging on the point light to move it around, or
• clicking the object to select it, and then editing its properties in the property editor panel in the top right of the Studio UI.

We can make the cube editable in the same way:

Making the camera editable is a little trickier, since just adding <e.perspectiveCamera/> will not in itself let r3f know that you want to use it for rendering. You could import the PerspectiveCamera component exposed by @react-three/drei and make it editable using const EditableCamera = e(PerspectiveCamera, 'perspectiveCamera'), however this is a little convoluted for such a common task, hence @theatre/r3f exposes a PerspectiveCamera component that you can use instead. This component exposes a makeDefault prop that you can use to let r3f know that you want to use it for rendering, and it is also editable.

Let's remove the camera prop from the Canvas element, and add our PerspectiveCamera component from @theatre/r3f.

#Animating objects

So far, we can move around these objects and edit their properties, but we can also animate them. To start animating, we first have to sequence the properties of an object we want to animate. To sequence properties: select an object, right-click on a property (or group of properties) in the property editor panel, and click "sequence". After clicking "sequence", the sequence editor will open. In this guide, we'll use the sequence editor to animate our cube to do a little dance.

To animate the cube's position, we'll create some keyframes by clicking in the Sequence Editor to move the playhead to a different time in the animation and then dragging the cube around or modifying its position properties. We use these keyframes to set where the cube will be at specific times in the animation.

Once we have some keyframes in the sequence editor, we can play our animation by pressing Space.

#Getting ready for production

So far, we've created some keyframes in the sequence editor that result in an animation. You can preview your animation by pressing Space. All the keyframes you created are saved in your browser's localStorage. So, your animation will be remembered between page refreshes. But now you may want a way to save, share/publish, and programmatically play your animation.

To distribute your animation as a part of your website, export your Theatre.js Project by clicking on "Demo Project" in the outline menu in the top left of the UI, and then click the "Export Demo Project to JSON" button on the right.

This will download a JSON file state.json. Now, we can move state.json to the folder containing our web project, and import the JSON file:

Then replace our code from before:

with this new code:

We are now passing the saved animation state to getProject. By doing this, The Theatre.js Project will be initialized with the saved animation from state.json instead of with the animation saved in localStorage. Don't worry; any changes you make to your animation in Studio will still be saved to localStorage after you do this ( your edits will still survive page refreshes).

The last thing left is programmatically playing your animation. Perhaps you will want to play the animation when the App component mounts, or you may want to play it in response to events like a button-click. Here, we'll use code to play the animation in a useEffect inside our App component.

To play an animation, we need to get a reference to its sequence and call the play method on it. Sequence.play accepts a number of options. Here, we are going to instruct Theatre.js to play the animation forever and in the range between the 0 second and the 1 second mark:

In summary, your main.tsx should now have the following code:

To check what our page looks like without the Studio, we can press Alt/Option + \ to hide it. Alternatively, we can comment out studio.initialize().

#Deploying to production

When we are done and ready to deploy our webpage to production, we only need to do two things.

1. Make sure that we have the latest project state exported to a JSON file and passed to getProject.
2. Remove studio.initialize and studio.extend.

We can also achieve the last step without manually editing the code every time by using environment-checks and relying on our bundler's tree-shaking feature:

#Next steps

In this guide, we walked through how Theatre.js can be used to bring animations to our R3F projects. Consider taking your project a step further by learning a more in-depth topic from our manual:

Additionally, learn more about Theatre.js' concepts. If you need any help or would like to share what you're working on with our community, please join the Theatre.js Discord.

---