Skip to content

Astro scroll animations without hydration

Use @awesome-reveal/astro to add scroll animations to Astro 6 and 7 sites. Install the package, and import Reveal and Cascade in your .astro files. The package does not use a UI framework, so it needs no client:* directive and no stylesheet import:

---
import { Cascade, Reveal } from "@awesome-reveal/astro";
---
<Reveal as="h1" from="left">
Scroll animations in Astro
</Reveal>
<Cascade as="ul">
<li>Fast</li>
<li>Small</li>
<li>Accessible</li>
</Cascade>

Each Reveal and Cascade renders its tag inside an awesome-reveal custom element. The custom element has display: contents, so it does not change the layout. But the child combinator (>), :nth-child() and parentElement see it. To control the entrance from a client script, use getReveal.

Astro adds the stylesheet and a small module script of the package to the page. The stylesheet hides the waiting elements in the server HTML. The script defines the custom element, and the custom element attaches its tag to the viewport observer. Without JavaScript, the content shows.

The HTML parser moves some tags out of the awesome-reveal element. Obey these rules:

  • Do not put Reveal or Cascade directly in a <table>, a table section, a row or a <select>. Reveal the whole table, or reveal content inside a table cell.
  • In a <p>, also inline in MDX text, use an inline tag, such as as="span".
<Reveal as="table">
<tbody>
<tr>
<td>The whole table reveals together.</td>
</tr>
</tbody>
</Reveal>
<p>
Reveal{" "}
<Reveal as="span" from={{ opacity: 0 }}>
a part of the text
</Reveal>
.
</p>

If the parser moves the tag, the browser console shows an error. After a few seconds, the tag shows with no entrance.

as does not accept the document tags (html, head and body), the table parts or the SVG-only tags. TypeScript rejects them.

Reveals work with the <ClientRouter />, with no setup. After a navigation, each new awesome-reveal element attaches itself.

An element with transition:persist keeps its state. If it revealed before the navigation, its entrance does not play again. Put transition:persist on an ancestor, or directly on Reveal:

<Reveal as="h2" transition:persist="intro">
Reveals one time across navigations
</Reveal>

The package does not need the astro:page-load event. Your own scripts that call getReveal need it, because the <ClientRouter /> does not run a processed <script> again after a navigation. Each navigation renders new elements, except the elements with transition:persist. Get the elements and call getReveal again in the listener:

<script>
import { getReveal } from "@awesome-reveal/astro";
document.addEventListener("astro:page-load", () => {
const details = document.querySelector("#details");
if (details) getReveal(details).when = true;
});
</script>

A prerendered page does not animate until the browser activates it.

A Reveal inside a server island reveals when Astro adds the island to the page. You do not need a step:

---
import ServerTime from "../components/ServerTime.astro";
---
<ServerTime server:defer>
<p slot="fallback">Loading...</p>
</ServerTime>
src/components/ServerTime.astro
---
import { Reveal } from "@awesome-reveal/astro";
---
<Reveal>Rendered at {new Date().toLocaleTimeString()}</Reveal>

The package writes no style attribute, no inline script and no CSS at runtime. But Astro can put the package stylesheet and your scripts inline in the HTML. Use one of these setups:

  • Set security.csp to true. Astro adds a <meta> policy with hashes for the inline styles and scripts that it adds. Astro does not support this option with the <ClientRouter />.
  • Send your own policy, such as style-src 'self'; script-src 'self', and set build.inlineStylesheets to 'never'. Also make sure that the built HTML has no inline <script> that your policy blocks.

Astro adds the security.csp policy only to the build. To check a policy, use astro build and astro preview.

With the default build.inlineStylesheets: 'auto', Astro puts a stylesheet smaller than 4 kB in a <style> element. If your policy blocks the package stylesheet, the content does not hide before the reveal, and the awesome-reveal element changes the layout.

@awesome-reveal/astro animates Astro markup. Inside a React or Vue island, use the package of that framework. See React or Vue in Astro.