Animate elements on a page (entrance, scroll, hover, timeline)

There are three ways to put motion on a hosted page. Pick one per element before building anything:

The Tailwind animation classes animate-spin, animate-ping, animate-pulse and animate-bounce also work on a hosted page (tested: animate-pulse ran).

For the page record itself, see Build a website page. For the header and footer, see Shared header and footer. For making the page work on phones, see Make a page work on phones and tablets.

Ask first

• Which page, and which elements? Name each one ("the hero heading", "the three feature cards", "the 12,500 customers number").
• What should each do, and when? Fade or slide in, grow, spin, count up, follow the scroll. When: on load, when scrolled into view, on hover, on click, or tied to the scroll position.
• Once or every time? Scroll-into-view plays once by default.
• Is it in the header or footer? The Animate panel can't animate those (step 1). Use CSS and JavaScript in root's Page settings instead (step 4).
• Is the page live? On a site that serves drafts, a save is live at once.

Steps

1. Build Studio: read the page and mark each element

Read the whole page: repo_find on page with { "data.site": "<site>", "data.name": "<page>" }, then repo_find_one on page with its id. A find result is partial.

Find the screen that renders: the one whose id is data.activeScreenId, else screens[0]. Animations live in that screen's config.animations and act on elements in that screen's html.

Every element to animate needs a data-node-id, unique on the page:

• A page Build Studio has saved already has one on every element (n- plus 8 characters). Use the existing id. Never rename it: the animation is found by that id alone.
• HTML you write yourself: add your own, e.g. <h1 data-node-id="hero-title">. Build Studio keeps an id that is already there and only adds one where it's missing. Ids it adds are random, so you can't predict them.

<section class="stats">
  <h2 data-node-id="stats-title">Trusted by teams</h2>
  <ul class="cards" data-node-id="stats-cards">
    <li>Fast</li><li>Simple</li><li>Secure</li>
  </ul>
  <p><span data-node-id="stats-count">0</span> customers</p>
</section>

Hands on: the page id, the active screen's id, and the data-node-id of each element. Check: each id appears once in that screen's html.

2. Build Studio (Animate panel): each element's animation

On the canvas: select the element, then click the Play icon on its toolbar (or Show Animation Timeline in the right toolbar). The Animate panel opens beside the Props Editor. The toolbar icon turns violet once the element has an animation.

Through the API (or to check what the panel saved), each entry of config.animations is one record:

What each trigger does on the hosted site (all tested at 390 and 1440 px, base-app animate-runtime.ts 419–499):

An example: the heading rises in on load, the cards follow one by one when scrolled to, the number counts up.

{
  "stats-title": { "enabled": true, "presetId": "custom", "trigger": "load", "duration": 600, "ease": "outExpo",
    "states": [ { "style": { "opacity": 0, "translateY": "24px" } }, { "style": { "opacity": 1, "translateY": "0px" } } ] },
  "stats-cards": { "enabled": true, "presetId": "custom", "trigger": "inView", "target": "children", "stagger": 120, "duration": 500,
    "states": [ { "style": { "opacity": 0, "scale": 0.9 } }, { "style": { "opacity": 1, "scale": 1 } } ] },
  "stats-count": { "enabled": true, "presetId": "custom", "trigger": "inView", "duration": 2000, "ease": "outExpo",
    "counter": { "from": 0, "to": 12500, "separator": ",", "format": "{n}+" } }
}

Hands on: the config.animations object for the screen. Check: every key is a data-node-id in the screen's html; every entry has trigger and either states (2 or more), steps, counter, motionPath or params; no pose holds a width, height, padding, margin or fontSize in px.

3. Build Studio: save it

On the canvas: save the page. Build Studio writes the panel's map into the active screen's config.animations on every save (selective-virtual-dom.ts 1424–1436). Deleting an element drops its animation. Duplicate and paste give the copy new ids, so the copy has no animation; add it again.

Through the API: change the screen and send the whole screens array back. repo_update replaces each key of data you send, so { "screens": [...] } replaces all screens.

1. From the repo_find_one result, take data.screens.
2. In the active screen, set config.animations to the full map. Keep the screen's other config keys (variants, activeVariants).
3. repo_update on page with { "screens": <the whole array> }. Leave html alone; only the config changed.

page_write with html replaces the active screen's html and keeps its config. The new HTML must still carry the same data-node-ids, or the animations lose their elements.

Stop: on a site that serves drafts, the save is live. Show the person which elements move and how, and wait for yes.

Hands on: nothing new. Check: repo_find_one shows the map under data.screens[<active>].config.animations, and the screen's html is unchanged.

4. Build Studio: CSS-only motion (above the fold, header and footer)

Use this where the Animate panel can't reach or would flash.

• animate.css: add animate__animated animate__fadeInUp (any animate.css 4 name) in the Class tab, with animate__delay-1s…5s, animate__slow / slower / fast / faster, animate__repeat-1…3 / animate__infinite. It plays once on load from the first paint (tested). It doesn't wait for scroll.
• Reveal on scroll with your own CSS, the way PhaZZer's site does it: hide the element with a class, and add a class from page JavaScript when it comes into view.

/* page <head> <style>, or root's Page settings → Style for the whole site */
.reveal { opacity: 0; transform: translateY(28px); transition: opacity .6s, transform .6s; }
.reveal.in { opacity: 1; transform: none; }
@media (prefers-reduced-motion: reduce) { .reveal { opacity: 1; transform: none; transition: none; } }

// Page settings → Style → JavaScript
(function boot() {
  if (document.body && document.body.getAttribute('data-design-mode') === 'true') return;
  var els = document.querySelectorAll('.reveal:not(.in)');
  if (!els.length) return void setTimeout(boot, 30);
  if (!('IntersectionObserver' in window)) { els.forEach(function (el) { el.classList.add('in'); }); return; }
  var io = new IntersectionObserver(function (entries) {
    entries.forEach(function (e) { if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); } });
  });
  els.forEach(function (el) { io.observe(el); });
})();

Tested: the element sat at opacity 0 until scrolled to, then got in and showed. Write the JavaScript as in Build a website page step 4: page_write appends to what is there. For the header and footer, put both in root's Page settings → Style.

Hands on: nothing new. Check: the class is on the element in the screen HTML; for a reveal, the script is in style.javascript at the top level of the record.

5. Check it on the site

Open the page in a real browser (headless Chrome is fine) at 390, 768 and 1440 px wide. Wait until the page has finished starting up before judging a load animation.

• Every animated element ends in its resting state: getComputedStyle(el).opacity is 1, and its inline style holds only what the animation set.
• Scroll to each inView element; it plays once.
• At 390 px, window.innerWidth is still 390. If it is larger, a pose or element is wider than the phone (see Make a page work on phones and tablets).
• With reduced motion on (Chrome DevTools › Rendering › prefers-reduced-motion: reduce, or CDP Emulation.setEmulatedMedia with prefers-reduced-motion: reduce), nothing moves and everything is visible. Tested: the site skips every Animate-panel animation. animate.css cuts its own to 1 ms (its stylesheet's rule); your own CSS needs its own prefers-reduced-motion rule, as in step 4.

To turn all Animate-panel animations off on one page, switch off Animate content in the page's Page settings (data.animateContent: false). Tested: nothing played.

When it's done

Tell the person: the page, each animated element and what it does and when, which ones are animate.css or CSS reveals instead, that visitors who ask for reduced motion see no motion, and anything they asked for in the header or footer and how it was done. Open the page in Build Studio and on the site.

What it can't do yet

• Animations on root, a parent page or a wrapper page never play. Only the viewed page's active screen is read (base-app page-client.tsx 76–83).
• ?screen= previews play the active screen's animations, not the shown screen's.
• No play-before-load. load and inView elements show normally until the page has finished starting up, then jump to the first pose. Hiding them in CSS first leaves them invisible if the script never runs.
• presetId alone does nothing on the site, and the panel's preset apply functions don't exist there.
• scroll with steps does nothing; call steps run nothing.
• The panel can't author steps, playbackRate or motionPath.offset. Write them through the API.
• AI › Add Animation doesn't apply its result.
• The Animate tab's speed, repeat and delay aren't written to the element.
• Editing in the panel erases Counter, Text split, Motion path, Callbacks, Gap, Direction and playback rate (step 2).
• Captured poses carry pixel sizes onto the element, on the canvas and on the site (step 2).

Don'ts

• Don't change or reuse a data-node-id that has an animation.
• Don't write config.animations on root or a parent page; it never plays there.
• Don't send a partial screens array or a partial config; it replaces what is there.
• Don't rely on presetId; write states.
• Don't put width, height, padding, margin or font sizes in poses.
• Don't hide content that matters behind hover, or hide it in CSS waiting for an animation.
• Don't use the AI › Add Animation dialog and assume it saved anything.