Run a Scroll-Driven Animation only once

~

# The Code

If you’re here for just the code, you can import runOnce from the @bramus/sda-utilities package.

import { runOnce } from '@bramus/sda-utilities';

// Run the “fade-in” scroll-driven animation on the `#hero` element only once.
window.addEventListener('load', (e) => {
  const $hero = document.querySelector('#hero');
  runOnce($hero, 'fade-in');
});

To see this snippet in action in, go check out the demo.

The source code of the runOnce function itself is available on GitHub. You can check the package details on NPM.

~

# How to use

Call the runOnce function and pass in a reference to an element along with the name of the animation you want to run only once:

document.querySelectorAll(".photo").forEach(($photo) => {
  runOnce($photo, "animate-in");
});

The passed in animation name – here animate-in – is optional. When not passing in a name, all Scroll-Driven Animations attached to that element will only run once.

window.addEventListener("load", (e) => {
  document.querySelectorAll(".photo").forEach(($photo) => {
    runOnce($photo, "animate-in");
  });
});

~

# How it works

At its core, the code listens for the animationend event on the passed in element. From that element, the relevant animation is filtered out and then stopped.

$el.addEventListener('animationend', (e) => {

  const animation = animations.find((a) => a.animationName == e.animationName);

  if (shouldAnimationBeStopped(animation, animationName)) {
    animation.commitStyles();
    animation.cancel();
  }

});

To effectively stop the animation, the computed values of the animation’s current styles are written to the element using animation.commitStyles(); before animation.cancel(); ever gets called.

To prevent glitches upon removal, it’s best to set the animation-fill-mode to forwards or both. If you’ve not done this, the function will give you a warning on the Console that glitches might occur in this case.

~

# Demo

You can find a demo on CodePen:

See the Pen Run Scroll-Driven Animations only once by Bramus (@bramus) on CodePen.

To make it very clear when the animation was finished, a lime border is drawn around each subject that has reached that state.

~

# Spread the word

To help spread the contents of this post, feel free to retweet its announcement tweet:

New blogpost: “Run a Scroll-Driven Animation only once”

A small piece of JavaScript to run a scroll-driven animation only once.

🔗 https://t.co/kzsxrTIjQn

🏷️ #css #js #ScrollDrivenAnimations

— Bram.us (by @bramus) (@bramusblog) October 5, 2023

~

“Play Once” icon from the Phosphor Light Vol.4 icon pack