aa-toggle-playstate

aa-toggle-playstate is a tiny IntersectionObserver utility — drop it on any container and the library walks its direct children, calls getAnimations() on each, and pauses every Web Animations API timeline while the container is out of view. Resumes from the same phase when the container scrolls back in.

Works on:

• CSS @keyframes animations applied via the animation shorthand or animation-name.
• Anything started with element.animate({…}, {…}).

Doesn’t touch GSAP timelines (use ScrollTrigger for those).

Why

Background loops, marquees, gradient cycles — they keep running in the background and burn CPU/battery while the user is somewhere else on the page. getAnimations().pause() is the cheapest way to stop them; this attribute is the smallest possible API to wire it up.

How

Add the attribute to the container whose visibility should drive the play/pause. The lib walks element.children, so animations on the container itself aren’t toggled — apply them to a wrapping or nested element if you want them controlled too.

<div aa-toggle-playstate>
  <div class="ambient-loop"></div>     <!-- has @keyframes pulse infinite -->
  <div class="ambient-loop"></div>
</div>

Always-on; no opt-in needed. (Can be turned off globally via init({ scrollState: false }) along with the body scroll-state attributes.)

Live demo

Three CSS-keyframe dots pulsing in cascade. Scroll past them and the lib pauses each animation; scroll back and they resume from the same frame they were paused at — no restart, no flicker.

aa-toggle-playstate