Using GreenSock Animation Platform (GSAP) in Astro with View Transitions: A Step-by-Step Guide

In this guide, you will learn how to use GreenSock Animation Platform (GSAP) in an Astro application with View Transitions enabled. You will go through the process of setting up a new Astro project, enabling View Transitions, installing the gsap module, and animating a text box based on the state of a checkbox.

Prerequisites

You’ll need the following:

Node.js 18 or later

Create a new Astro application
Integrate GreenSock Animation Platform (GSAP) in your Astro project
Build and Test your Astro application locally

Create a new Astro application

Let’s get started by creating a new Astro project. Execute the following command:

npm create astro@latest my-app

npm create astro is the recommended way to scaffold an Astro project quickly.

When prompted, choose:

Empty when prompted on how to start the new project.
Yes when prompted if plan to write Typescript.
Strict when prompted how strict Typescript should be.
Yes when prompted to install dependencies.
Yes when prompted to initialize a git repository.

Once that’s done, you can move into the project directory and start the app:

cd my-app
npm run dev

The app should be running on localhost:4321.

Now, let’s move on to integrate GSAP in your Astro application.

Integrate GreenSock Animation Platform (GSAP) in your Astro project

Install GreenSock Animation Platform (GSAP) SDK

Execute the command below to install the necessary package for using GSAP:

npm install gsap

The command installs the following library:

gsap: A framework-agnostic JavaScript animation library.

Create a Shared Layout Component with View Transitions and GSAP

To use GSAP in multiple pages in your Astro application with ViewTransitions enabled, create a shared Layout to save the time of repeating the same code over each page. Create a file named Layout.astro in the src directory with the following code:

---
import { ViewTransitions } from "astro:transitions";
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <ViewTransitions />
    <title>Astro</title>
    <style is:global>
      .box {
        width: 100px;
        height: 100px;
        background: black;
      }
    </style>
  </head>
  <body>
    <slot />
    <script>
      import gsap from "gsap";
      window.gsap = gsap;
    </script>
  </body>
</html>

In the code above you’ve done the following to be able to re-use gsap everywhere:

Imported ViewTransitions and used it inside the <head> tag to update your page content without the browser’s normal, full-page navigation refresh.
Defined a CSS to visually create a 100x100 black box.
Imported the gsap module and made it accessible inside the window. So now, in any page wrapped in this Layout, you would be able to call gsap.to and expect it work as is even in an inline script. Note that bundled scripts run only once when View Transitions are enabled. This is helpful for you as you would not need to import and load the gsap module in each page.

As Giulio Zanchetta correctly suggested, update the src/env.d.ts to ensure support for gsap types across pages anywhere in the script tag:

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />
interface Window { 
  gsap: typeof import("gsap");
}

Use GSAP in multiple pages

To demonstrate usage of GSAP, you will animate a box left, right, up and down based on the checked state of an checkbox in multiple pages.

First, let’s create the box and the checkbox in the default index route. On this page, you will animate the box from left to right when the checkbox is toggled. Replace the existing code in src/pages/index.astro file with the following:

---
import Layout from "../Layout.astro";
---

<Layout>
  <h1>Astro</h1>
  <input type="checkbox" />
  <div class="box"></div>
  <a href="/second">Click Me</a>
</Layout>

In the code above, you’ve created a checkbox and a div element representing the box. Also, you’ve added a hyperlink to /second route.

Now, create a second.astro in the src/pages directory with the following code where you will animate the box up and down when the checkbox is toggled:

---
import Layout from "../Layout.astro";
---

<Layout>
  <h1>Astro</h1>
  <input type="checkbox" />
  <div class="box"></div>
  <a href="/">Click Me</a>
</Layout>

In the code above, you’ve created a checkbox and a div element representing the box. Also, you’ve added a hyperlink to / route.

Now, to animate the box using GSAP whenever the checkbox is clicked, make the following additions in one of route:

---
import Layout from "../Layout.astro";
---

<Layout>
  <h1>Astro</h1>
  <input type="checkbox" />
  <div class="box"></div>
  <a href="/second">Click Me</a>
  <script>
    document.addEventListener(
      "astro:page-load",
      () => {
        const element = document.querySelector('[type="checkbox"]');
        element?.addEventListener("change", () => {
          if (element.checked) gsap.to(".box", { x: 200 });
          else gsap.to(".box", { x: 0 });
        });
      },
      { once: false }
    );
  </script>
</Layout>

and the following change in the other route:

---
import Layout from "../Layout.astro";
---

<Layout>
  <h1>Astro</h1>
  <input type="checkbox" />
  <div class="box"></div>
  <a href="/">Click Me</a>
  <script>
    document.addEventListener(
      "astro:page-load",
      () => {
        const element = document.querySelector('[type="checkbox"]');
        element?.addEventListener("change", () => {
          if (element.checked) gsap.to(".box", { y: 200 });
          else gsap.to(".box", { y: 0 });
        });
      },
      { once: false }
    );
  </script>
</Layout>

In the additions above, you have created an event listener to the change event of the checkbox. This event is triggered whenever the checkbox is checked or un-checked. Further, depending on the state of the checkbox, you either animate the button to move 200 units to the right, or come back at it’s original position.

Note that the change event listener is wrapped under the following code:

document.addEventListener(
  "astro:page-load",
  () => {
  },
  { once: false }
);

The code above ensures that whenever the page containing it is visited, whether while navigating or as the first load, it runs in the browser. So to attach the listener on the box element after navigation to a new page or when a page is directly loaded, the astro:page-load event comes in handy. Also, using once: false makes sure that the code inside is re-ran if the page is visited multiple times during a session.

Build and Test your Astro application locally

To test the application, prepare a build and run the preview server using the command below:

npm run build && npm run preview

Conclusion

In this guide, you learned how to use GreenSock Animation Platform (GSAP) in an Astro application with View Transitions enabled.

If you have any questions or comments, feel free to reach out to me on Twitter.

Credits

Thanks to Martin for a detailed review and suggesting fixes in this article.