With HTML/SVG

In this tutorial, we will:

1. Show the Theatre.js Studio UI on a simple HTML page
2. Create a new Theatre.js Project which will control JavaScript values on the page
3. Use Theatre.js to animate UI elements on our page
4. Create a production (publishable) version of our Project we can share with users, collaborators, or friends

#Prerequisites

Let's start by creating a basic HTML file called animation-tutorial.html. Below is a starter HTML file. It only contains the basic tags an HTML page should have, nothing Theatre.js specific yet.

If we've saved the above HTML in a file called animation-tutorial.html and open that file in our browser, it results in a Welcome page that looks like the following:

#Add Theatre.js Studio

To add functionality to our static HTML page, we should first set up our Theatre.js Project. Let's add the following JS into the <script> towards the bottom of the HTML where it says // Add JavaScript here:

Now when we open / refresh the Welcome page in our browser, we should see the Theatre.js Studio on top of the HTML Welcome page. There's an "Outline Menu" button in the top left of the page and a "..." menu and "Property Editor" button in the top right:

Now that we've gotten the Studio to appear, let's create a Theatre.js Project called 'HTML Animation Tutorial' containing a Sheet called 'Sheet 1' and an Object called 'Heading 1' with props "y" and "opacity":

Now we should see HTML Animation Tutorial > Sheet 1: Default > Heading 1 under the "Outline Menu" button in the top left of our page.

We've just configured our Theatre.js Project structure, but if we try to change any values in the Details Panel on the right, they will not yet change any part of the original HTML Welcome page.

Next, let's ensure the values in Theatre.js are applied to our page's elements. We can call the Object.onValuesChange method on obj to listen to the value changes on our Object.

Now that our code synchronizes Theatre.js with the articleHeadingElement's style, try dragging or clicking on the number beside "y" or "opacity" in the Details Panel on the right in the preview below.

The "Welcome" element you see moving around and fading in and out should behave like in the video below.

#Sequencing Properties to create an animation

Now that we have set up our Project, let's go ahead and use the Studio to create an animation. In Theatre.js, an animation consists of a set of "Sequenced" props with "Keyframes".

First, let's try Sequencing the "y" prop and adding keyframes to it. Check the video below to see how we can sequence a prop.

Now that we've sequenced a prop and added keyframes, we can play back the resulting animation in our browser. But the animation is, so far, only stored in your browser's local data (in localStorage). To share the animation with others (or include it on a website), we have to export the animation state and initialize our Theatre.js project with it. We'll look at that in the next section.

#Getting ready for production

Now that we've created a basic animation locally, we want to share it with the world! So, here's a checklist for what we need to do to share our animation / include it on a webpage.

Production (published webpage) animation checklist:

1. Export the Project's state.json by clicking the Project ("HTML Animation Tutorial") in the outline panel on the left and then click the "Export HTML Animation Tutorial to JSON" in the panel on the right. A file download for state.json should start in your browser.

2. Open state.json in a text editor and copy its contents into your JavaScript code as a value stored in a projectState variable (if you use a bundler, it's possible to import the state.json file directly).

3. In the part of the code where you created the Theatre.js Project, modify it to include your animation state like so:

   
   

   const project = core.getProject('HTML Animation Tutorial', {

   state: projectState,

   })

   
   

4. Remove Studio imports

   a. for simple projects using @theatre/browser-bundles, remove the core-and-studio.js part of the import URL, and replace it with core-only.min.js.

   b. for projects directly importing from @theatre/studio (using a bundler), don't import Studio for your production builds.

5. Remove all Theatre.studio.initialize() calls so that the animation shows, but the Studio UI does not.

6. Add some code that plays the animation! Here's some code that plays 6 seconds of the animation and loops it as soon as it has loaded:

   
   

   project.ready.then(() => {

   sheet.sequence.play({ iterationCount: Infinity, range: [0, 6] })

   })

   
   

The following shows our production HTML version of animation-tutorial.html which applies the above and uses a project JSON state the author designed while writing this tutorial.

And here's the final product.

#Next steps

Want to learn more ways to use Theatre.js? Check out another getting started guide:

Also, take a look at some more in-depth topics from our manual:

---