12k
All articles

A Guide to Accessible Animations with GSAP

Build accessible GSAP animations with matchMedia and prefers-reduced-motion. Simplify ScrollTrigger effects, add pause controls, keep content visible, and test motion settings.

OpenReplay Team
OpenReplay Team
A Guide to Accessible Animations with GSAP

The standard way to handle prefers-reduced-motion in GSAP is gsap.matchMedia() with a conditions object: GSAP runs your setup function for whichever motion preference matches, and when the user changes that setting it reverts everything the function created and runs it again.

Teams usually come to this after an accessibility audit flags a scroll-pinned hero or a looping marquee, and the designers don’t want the page turned into a static PDF to fix it.

Checking the media query is only part of the work. An accessible GSAP setup also needs calmer ScrollTriggers, a pause control, content that stays visible if the script never runs, and a way to test all of it. If you need the background on the media query itself, read OpenReplay’s guide to prefers-reduced-motion. gsap.matchMedia() requires GSAP 3.11.0 or later.

Key Takeaways

  • gsap.matchMedia() reverts every animation and ScrollTrigger created in a setup function when its query stops matching, so a change to the OS reduce-motion setting takes effect without a page reload.
  • For reduced motion, swap large movement, rotation and scale for a short opacity fade so the content still appears.
  • A reduced-motion ScrollTrigger branch should drop pin and scrub and simply fade each element in as it enters the viewport.
  • WCAG 2.2.2 Pause, Stop, Hide (Level A) requires a pause, stop or hide control for automatic motion. A prefers-reduced-motion check does not meet it on its own.
  • Leave animated content readable in its default CSS state, so nothing stays at opacity: 0 if no animation runs.

Branching on GSAP Prefers Reduced Motion with gsap.matchMedia()

gsap.matchMedia() runs a setup function only while its query matches. When the query stops matching, it reverts every animation and ScrollTrigger the function created. You can pass a conditions object as the query, and the handler then reads each condition as a boolean from context.conditions.

const mm = gsap.matchMedia();
const conditions = {
  isMotion: "(prefers-reduced-motion: no-preference)",
  isReduced: "(prefers-reduced-motion: reduce)",
};

mm.add(conditions, (context) => {
  const { isMotion, isReduced } = context.conditions;

  if (isMotion) {
    gsap.from(".hero-card", { opacity: 0, x: -200, rotation: -8, duration: 1 });
  }
  if (isReduced) {
    gsap.from(".hero-card", { opacity: 0, duration: 0.4 });
  }
});

Aim to reduce motion, not remove it. In the reduced branch, the large horizontal travel and the rotation become a short fade. The card still appears and still draws attention to itself, but nothing moves across the screen. GSAP’s accessible animation guide gives a rubric for when to simplify an animation and when to drop it entirely. matchMedia() wraps gsap.context() internally, so don’t wrap it in a second context.

Calming ScrollTrigger for Reduced Motion

A reduced-motion ScrollTrigger branch should drop pin and scrub and fade each element in as it enters the viewport. Pinning takes over the user’s scrolling, and scrubbing ties movement to every scroll gesture. Both are what the reduced branch is meant to avoid.

mm.add(conditions, (context) => {
  if (context.conditions.isMotion) {
    const tl = gsap.timeline({
      scrollTrigger: { trigger: ".story", pin: true, scrub: 1, end: "+=200%" },
    });
    tl.from(".story-step", { opacity: 0, y: 100, stagger: 0.5 });
  } else {
    gsap.utils.toArray(".story-step").forEach((step) => {
      gsap.from(step, { opacity: 0, duration: 0.4, scrollTrigger: { trigger: step } });
    });
  }
});

In its simplest form, a ScrollTrigger plays its animation once, when the trigger element enters the viewport. That suits a fade. You don’t have to kill anything by hand: if the preference changes, matchMedia reverts the pinned timeline and builds the fade version. For pinning and scrub patterns on the full-motion side, see OpenReplay’s ScrollTrigger walkthrough. Session replays can show users scrolling quickly past pinned sections or stopping partway through an animation, which points to where the motion is getting in their way.

Pause Controls and an In-Page Motion Toggle

WCAG 2.2.2 Pause, Stop, Hide is a Level A criterion that requires a way to pause, stop or hide moving content that starts automatically, lasts more than five seconds and appears alongside other content. Respecting prefers-reduced-motion does not satisfy WCAG 2.2.2, because users who never changed their OS setting still see the full animation. The W3C Understanding document for 2.2.2 also recommends that if a page contains more than one moving, blinking, scrolling or auto-updating element, you provide a single mechanism that controls all of them.

CriterionLevelGSAP technique
2.2.2 Pause, Stop, HideAPause button calling timeline.pause() / timeline.play()
2.3.3 Animation from InteractionsAAAgsap.matchMedia() reduced-motion branch

WCAG 2.2.2 and 2.3.3 cover different motion. 2.3.3 applies to motion triggered by user interaction, and 2.2.2 applies to motion the page starts by itself. OpenReplay’s accessible animations overview covers the broader guidelines.

const toggle = document.querySelector("#reduce-motion");
const pauseBtn = document.querySelector("#pause-motion");
toggle.checked = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
toggle.addEventListener("change", gsap.matchMediaRefresh);

mm.add(conditions, (context) => {
  const reduce = context.conditions.isReduced || toggle.checked;
  pauseBtn.hidden = reduce;
  if (reduce) return; // marquee stays static

  const tl = gsap.timeline({ repeat: -1 });
  tl.to(".marquee-track", { xPercent: -50, duration: 20, ease: "none" });
  pauseBtn.textContent = "Pause animation";

  const onClick = () => {
    tl.paused() ? tl.play() : tl.pause();
    pauseBtn.textContent = tl.paused() ? "Play animation" : "Pause animation";
  };
  pauseBtn.addEventListener("click", onClick);
  return () => pauseBtn.removeEventListener("click", onClick);
});

pause() pauses the instance and can optionally jump to a specific time. With no argument, it stops where the playhead currently is. play() resumes from that point and makes sure the instance is neither paused nor reversed. paused() with no argument works as a getter, so you can use it to toggle.

gsap.matchMediaRefresh() reverts every active matchMedia setup and runs again the ones that still match, so the checkbox rebuilds every animation immediately. The rule in reduce = isReduced || toggle.checked is that the toggle can add reduction but can never override an OS request for reduced motion. The cleanup function only removes the listener. Don’t call context.revert() in it, because matchMedia handles the revert itself.

Keeping Content Visible if Animation Never Runs

Animated content should be fully readable in its default CSS state. Then, if the script fails or no matchMedia branch runs, nothing is left at opacity: 0 or visibility: hidden. This happens in practice: a gsap.matchMedia() handler built on a conditions object doesn’t run at all when none of the conditions match.

/* Avoid: content is invisible until JavaScript reveals it */
.reveal { opacity: 0; }
// Prefer: CSS leaves .reveal visible; GSAP animates from hidden to that state
mm.add(conditions, () => {
  gsap.from(".reveal", { opacity: 0, duration: 0.4 });
});

gsap.from() animates from the values you pass to the element’s current state. That means the resting state stays visible, and only the animation ever hides the element. The same goes for autoAlpha, GSAP’s combined opacity and visibility property: animate content from autoAlpha: 0 instead of hiding it in CSS with opacity: 0 and visibility: hidden and waiting for a tween to reveal it.

Focus Order When Elements Move

GSAP transforms such as x, y and scale move an element visually but leave its position in the DOM unchanged. Keyboard focus and screen-reader order therefore follow the markup, not the animation. Keep the DOM in a logical reading order and don’t animate layout properties to fake a different one.

Don’t move an element while it has focus, and don’t make an interactive element clickable before it has settled. A button sliding under the cursor is a target that moves away. For animated text, SplitText handles screen readers by default. With aria: "auto", it adds an aria-label to the split element, filled from its text, and adds aria-hidden to the line, word and character elements inside it. That way the accessibility tree exposes one readable string instead of separate fragments. That default works on headings, but ARIA prohibits aria-label on generic elements such as a plain <div>, <span> or <p>, and accessibility checkers flag it there. For those elements, or if the split text contains nested links that must be announced, use aria: "none", which adds no ARIA attributes, and provide a screen-reader-only copy of the text.

How Do You Test Reduced Motion in GSAP?

Test both GSAP motion branches by toggling the reduced-motion preference while the page is open. Because gsap.matchMedia() responds to changes, you should see the animations swap without reloading. Turn on the OS reduce-motion setting (see MDN’s prefers-reduced-motion user preferences for where it lives on each platform), or emulate it in Chrome. In Chrome DevTools, open the Rendering tab, find “Emulate CSS media feature prefers-reduced-motion” and select prefers-reduced-motion: reduce.

Check these:

  1. Pinned sections no longer pin.
  2. Looping motion is either gone or has a working pause button you can reach with the keyboard.
  3. With JavaScript disabled, all content is still visible.
  4. The in-page toggle rebuilds the animations immediately.

Conclusion

An accessible GSAP setup keeps the design and gives users control over it. matchMedia swaps big movement for fades and stays in sync with the OS setting, ScrollTrigger stops pinning in the reduced branch, a real button pauses anything long-running, and content stays visible without JavaScript. Start with the pinned or looping animation your audit flagged, write its reduced branch and pause control, and test both with DevTools emulation before moving on to the next one.

FAQs

How do I use gsap.matchMedia() for reduced motion in React?

Create the matchMedia instance inside the effect and return a cleanup function that calls mm.revert(). Reverting the instance reverts every animation and ScrollTrigger its handlers created, so a separate gsap.context() is unnecessary. The cleanup matters in development because React Strict Mode mounts, unmounts and remounts components, which can otherwise start the same animation twice.

Does a CSS prefers-reduced-motion reset stop GSAP animations?

No. A global CSS rule that shortens animation and transition durations inside a prefers-reduced-motion: reduce block only affects CSS animations and transitions. GSAP animates from JavaScript by writing inline style values on every frame, so its tweens and ScrollTriggers keep running. Handle GSAP motion with a gsap.matchMedia() reduced branch, and keep the CSS reset for CSS-driven motion.

What happens to a running GSAP animation when the user changes the reduced-motion setting?

gsap.matchMedia() reverts it and runs the handler again for the new preference. Reverting removes the inline styles the animations added and reverts ScrollTriggers created in the handler, including their pinning. The newly matching branch then builds its animations from scratch, so a half-finished full-motion tween does not resume. The reduced version starts from the element's default CSS state.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.