Post Serie Archives:

Example Scroll-Linked Animation with Element-Based Offsets, CSS FTW! 🤩

~

~

~

# Scroll-Linked Animations (Part 1), a Recap

In the first part of this series we took a look at @scroll-timeline and its descriptors. If I explained it all properly, the code snippet below should make sense:

@keyframes resize-progressbar {
  to {
    transform: scaleX(1);
  }
}

@scroll-timeline scroll-in-gallery {
  source: selector(#gallery__scrollcontainer);
  scroll-offsets: 0%, 100%;
  orientation: horizontal;
  time-range: 1s;
}

#gallery__progressbar {
  transform: scaleX(0.5);
  animation: 1s linear forwards resize-progressbar;
  animation-timeline: scroll-in-gallery;
}

~

# Element-based Offsets?

Besides setting absolute values as scroll-offsets, the Scroll-Linked Animations Specification also allows you to set Element-based Scroll Offsets. With this type of Scroll Offsets the animation is based on the location of an element within the scroll-container.

Typically this is used to animate an element as it comes into the scrollport until it has left the scrollport; e.g. while it is intersecting:

See the Pen Scroll-Linked Animations Visualization: Element-Based Offsets by Bramus (@bramus) on CodePen.

When scrolling down in the visualization (using the ⏭ button) you’ll see the box switch colors:

1. as it slides into the scrollport from the bottom
2. after it has just left the scrollport at the top

Both these turning points can be used as offsets for a Scroll-Linked Animations. Because they are described from the perspective of the box itself (which is an HTML Element), we call these “Element-based Offsets”.

In pseudo-code, our @scroll-timeline would look like this:

@scroll-timeline element-enters-and-leaves-the-scrollport {
  scroll-offsets:
    “the box is positioned underneath the bottom edge of the scrollport”,
    “the box is positioned above the top edge of the scrollport”
  ;
  time-range: 1s;
}

As with “regular” Scroll-Linked Animations we can drive an animation while scrolling between these two Element-based Offsets.

@scroll-timeline element-enters-and-leaves-the-scrollport {
    start: “the box is positioned underneath the bottom edge of the scrollport”;
    end: “the box is positioned above the top edge of the scrollport”;
    time-range: 1s;
}

~

# Element-based Offsets in CSS

To create a Scroll-Linked Animation that uses Element-based Offsets, we first need two Element-based Offsets:

1. A from offset which defines when the animation will begin.
2. A to offset which defines by when the animation will be done.

In CSS, these Element-based Offsets are represented by the <element-offset> Data Type.

~

# The <element-offset> Data Type

Let’s take the example below and dissect it:

selector(#element) end 0

1. selector(#element) defines the DOM Element we want keep an eye on. We call this the target.

2. end indicates at which edge of the source‘s scrollport the algorithm should look for the target intersecting.

   • Allowed values are start/end.
   • Depending on the timeline’s orientation this translates to the top/bottom or left/right edge.

3. The threshold is a number — ranging from 0.0 to 1.0 — that indicates how much of the target is visible in the scrollport at the given edge.

   • 0 = not in the scrollport
   • 1 = entirely in the scrollport

   You might already know this value from creating an IntersectionObserver.

~

# Making it visual

If you cannot follow with that threshold there, don’t worry: it’s easier to understand if you make it visual.

See the Pen Scroll-Linked Animations Visualization: Element-Based Offsets Visualizer by Bramus (@bramus) on CodePen.

In the visualization above try changing the values, keeping in mind that the threshold is a number that indicates how much of the target is intersecting with the scrollport at the given edge.

If, after playing with it, you understand that a edge+threshold combo of start 0.5 means that the target is halfway across the top edge of a vertical scrollport, you get it 😎

~

# Element-based Offsets and @scroll-timeline (Revealing Image Demo)

To create a Scroll-Linked Animation that uses Element-based Offsets, you need to pass a pair of <element-offset> Data Types into the @scroll-timeline‘s scroll-offsets descriptor.

@scroll-timeline element-enters-and-leaves-the-scrollport {
  scroll-offsets:
    selector(#element) end 0,
    selector(#element) start 0
  ;
  time-range: 1s;
}

1. selector(#element) end 0 here is our from offset, and defines when the animation will begin.
2. selector(#element) start 0 here is our to offset, and defines by when the animation will be done.

Here the offsets for our @scroll-timeline are set so that the animation will begin when #element is about to enter the scrollport from the bottom (= end edge, 0% in view), and will be done animating after the #element has entirely left the scrollport at the top (= start edge, 0% in view).

In this demo you’ll see an image be revealed as it intersects with the scrollport. The reveal itself is done using a clip-path that animates from inset(0% 50% 0% 50%); to no clipping at all, which looks like a curtain opening.

@keyframes reveal {
    to {
        clip-path: inset(0% 0% 0% 0%);
    }
}
.revealing-image {
    clip-path: inset(0% 50% 0% 50%);
    animation: reveal 2s linear;
    animation-fill-mode: forwards;
}

@scroll-timeline revealing-image-timeline {
    source: selector(body);
    scroll-offsets:
      selector(#revealing-image) end 0,
      selector(#revealing-image) start 0
    ;
    time-range: 2s;
}
#revealing-image {
    animation-timeline: revealing-image-timeline;
}

~

# Typical from/to <element-offset> Combinations

There are 4 typical edge + threshold combinations to use with Scroll-Linked Animations:

• start 0
• start 1
• end 1
• end 0

Depending on how you combine these as to/from offsets, we can control when exactly the animation will run:

• #element is intersecting scrollport, even for the tiniest bit
• #element is in between scrollport edges
• #element is entering from bottom into scrollport
• #element is exiting at top from scrollport

In the demo below I’ve created several boxes that each have a different pair of <element-offset>s applied. Scroll down to see the elements appear in the viewport and take a good look at each box separately, specifically when one of its edges enters or leaves the viewport.

Color codes are applied to indicate when the element is being animated:

• Red = the Scroll Timeline is not animating the element
• Green = the Scroll Timeline is animating the element

Did you see? Hit the checkbox at the top to have the demo show the findings. Perhaps you’ll see it now 😉

Interpreting the results from the demo, I’ve forged this small list of typical from-to offset combinations and what they look like:

• end 0 → start 0 = intersecting scrollport, even for the tiniest bit
• end 1 → start 1 = in between scrollport edges
• end 0 → end 1 = enter from bottom into scrollport
• start 1 → start 0 = exit at top from scrollport

In this extra visualization below you can see how these different combinations affect the timeline (drawn in the center). The same colors as in the demo are used.

See the Pen Scroll-Linked Animations Visualization: Element-Based Offsets Timeline Visualizer by Bramus (@bramus) on CodePen.

~

# Demos

As I have been playing with CSS @scroll-timeline for nearly a month by now, I’ve whipped up quite a lot of extra demos. Ready to have your socks blown off? Here goes:

1. Revealing Images Demo, Revisited
2. Contact List Demo
3. Contact List Demo, Revisited
4. Horizontal Scroll Section Demo
5. CoverFlow Demo
6. Stacking Cards Demo

~

# Revealing Images Demo, Revisited

This demo is similar to the first Revealing Image one, yet the offsets were tweaked in such a way that the revealing animation should only start when the image is already halfway in view (read: threshold of 0.5) and be finished by the time the image has entered the scrollport completely.

In @scroll-timeline speak that becomes:

@scroll-timeline revealing-image-timeline-1 {
  source: selector(body);
  scroll-offsets:
    selector(#revealing-image-1) end 0.5,
    selector(#revealing-image-1) end 1
  ;
  time-range: 2s;
}

Above that the start clip-path was set to inset(45% 20% 45% 20%); — making it look like a revealing box — and the opacity is also animated.

.revealing-image {
  opacity: 0;
  clip-path: inset(45% 20% 45% 20%);
  …
}

~

# Contact List Demo

In this demo I’ve created a contact list where new items slide in when they enter the scrollport. I think it makes a neat effect 🙂

The list itself is a regular <ul> which acts as the @scroll-timeline‘s source. Each <li> has it’s own scroll-offset set to go from end 0 (= bottom edge, out of view) to end 1 (= bottom edge, in view).

@keyframes slide-in {
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

li {
  opacity: 0;
  transform: translateX(-100%);
  animation: 1s slide-in ease-in forwards;
}

@scroll-timeline list-item-15 {
  source: selector(#list-view);
  scroll-offsets:
    selector(#list-item-15) end 0,
    selector(#list-item-15) end 1
  ;
  time-range: 1s;
}
#list-item-15 {
  animation-timeline: list-item-15;
}

const generateCSS = () => {
  const css = [];
  document.querySelectorAll('li').forEach((li, i) => {
    const id = li.getAttribute('id');

    css.push(`
      @scroll-timeline list-item-${id} {
        source: selector(#list-view);
        scroll-offsets:
          selector(#${id}) end 0,
          selector(#${id}) end 1
        ;
        time-range: 1s;
      }
      #${id} {
        animation-timeline: list-item-${id};
      }   

    `);
  });
  return css.join("\n");
}

const injectCSS = (css) => {
  const style = document.createElement('style');
  style.innerHTML = css;
  document.head.appendChild(style);
}

injectCSS(generateCSS());

The animation on the <li>s in this demo was carefully chosen to be a horizontal one, so that the dimensions of the of the wrapping <ul>‘s scrollport don’t change. If the <li> elements would be translated in a vertical direction, that would also adjust the scrollport. You can work around this by animating not the <li> itself, but by animating its contents.

@keyframes slide-out {
  to {
    opacity: 0;
    transform: translateX(100%);
  }
}

li {
  opacity: 1;
  transform: translateX(0);
  animation: 1s slide-out ease-in forwards;
}

@scroll-timeline list-item-1 {
  source: selector(#list-view);
  scroll-offsets:
    selector(#list-item-1) start 1,
    selector(#list-item-1) start 0
  ;
  time-range: 1s;
}
#list-item-1 {
  animation-timeline: list-item-1;
}

~

# Contact List Demo, Revisited

Combining both the fly-in and fly-out effect is possible by creating 2 animations, each with their own individual (non-overlapping) @scroll-timeline

/* Element scrolls into the scroll-container (from the bottom) */
@scroll-timeline tl-list-item-12-appear {
  source: selector(#list-view);
  scroll-offsets:
    selector(#list-item-12) end 0,
    selector(#list-item-12) end 1
  ;
  time-range: 1s;
}

/* Element scrolls out of the scroll-container (at the top) */
@scroll-timeline tl-list-item-12-disappear {
  source: selector(#list-view);
  scroll-offsets:
    selector(#list-item-12) start 1,
    selector(#list-item-12) start 0
  ;
  time-range: 1s;
}

#list-item-12 > * {
  animation:
    1s li-appear linear tl-list-item-12-appear,
    1s li-disappear linear tl-list-item-12-disappear
  ;
}

What’s very crucial here — apart from having non-overlapping Scroll Timelines — is the attaching of the animations. Whereas in the previous demos it had animation-fill-mode: both; set, this has now been removed. This is a very important thing to do. If you don’t you’ll notice that only the last animation will be applied and might think this is an implementation bug as I did. Thankfully it’s not a bug and was a classic case of PEBKAC.

~

# Horizontal Scroll Section Demo

This demo is based upon this “GSAP ScrollTrigger & Locomotive Scroll” demo by Cameron Knight, which features a horizontal scroll section. I’ve basically left the HTML intact, removed all JS, and added a few CSS Animations + Scroll Timelines to get this working.

The tricky part was the horizontal section of course:

1. Stretch out the wrapping #sectionPin to 500vh so that we create extra room to scroll.

2. Set up a @scroll-timeline for #sectionPin while it’s inside entirely covering the scrollport, using the mind-flipping start 1 → end 1 offset combination.

   @scroll-timeline horizontal-section-scrolling-into-view {
     source: selector(body);
     scroll-offsets:
       selector(#sectionPin) start 1, /* Start when #sectionPin touches the top edge of the scrollport and is visible inside the scrollport */
       selector(#sectionPin) end 1 /* End when #sectionPin touches the bottom edge of the scrollport and is visible inside the scrollport */
     :
     time-range: 1s;
   }

   This weird offset combination only works because #sectionPin is bigger than the scrollport. I’ll leave it to you, the reader, to dig into it further 😉

3. On .pin-wrap use position: sticky; (so that it remains in view) and translate it horizontally while scrolling.

   @keyframes move-horizontal-scrolling-section {
     to {
       transform: translateX(calc(-100% + 100vw)); /* Move horizontally so that right edge is aligned against the viewport */
     }
   }
     
   .pin-wrap {
     position: sticky;
     top: 0;
   
     animation: 1s linear move-horizontal-scrolling-section forwards;
     animation-timeline: horizontal-section-scrolling-into-view;
   }

~

# CoverFlow Demo

Remember CoverFlow from iTunes? Well, here’s a CSS-only version built with @scroll-timeline! 🎉

Looking under hood, here’s how it’s structured:

1. The <ul> element is the scroll container, and the <li> elements inside scroll.
2. The <li> elements themselves switch z-index, and their contained <img /> elements are transformed.

That 2nd thing is quite key here: If we were to transform the <li> elements the scroll-container’s width would change. This would make the scroll-linked animation recalculate at every change, resulting in a flickering animation. We don’t want that of course.

~

# Stacking Cards Demo

In this demo I tried recreating this Stacking Cards demo from CodyHouse, initially by Claudia Romano.

Thanks to playing with animation-delay I’m able to use one shared @scroll-timeline for each card

:root {
  --numcards: 4;
}

#card_1 { --index: 1; }
#card_2 { --index: 2; }
#card_3 { --index: 3; }
#card_4 { --index: 4; }

@scroll-timeline cards-element-scrolls-in-body {
  source: selector(body);
  scroll-offsets:
    selector(#cards) start 1, /* Start when the start edge touches the top of the scrollport */
    selector(#cards) start 0 /* End when the start edge touches the start of the scrollport */
  ;
  time-range: 4s;
}

.card {
  --index0: calc(var(--index) - 1); /* 0-based index */
  --reverse-index: calc(var(--numcards) - var(--index0)); /* reverse index */
  --reverse-index0: calc(var(--reverse-index) - 1); /* 0-based reverse index */
}

@keyframes scale {
  to {
    transform: scale(calc(1.1 - calc(0.1 * var(--reverse-index))));
  }
}
	
.card__content {
  transform-origin: 50% 0%;
  will-change: transform;

  --duration: calc(var(--reverse-index0) * 1s);
  --delay: calc(var(--index0) * 1s);
  
  animation: var(--duration) linear scale var(--delay) forwards;
  animation-timeline: cards-element-scrolls-in-body;
}

At first I struggled a lot with getting the sticky part right, as my position: sticky; would work as expected, but not as I wanted: the last card slid over the preceding ones:

After doing a detour with manually trying to translate the cards, I eventually found how to get my position: sticky; to work as I wanted.

1. Don’t vary top by an extra 1em per sticky item, but fixate top: 0; and adjust the padding-top to achieve the offset.
2. Lay out all cards in their wrapper using CSS Grid with fixated rows. Their padding simply bleeds out (huh? 🤯), and therefore they will be evenly spaced using gap.

Cool part is: browsers that don’t understand @​scroll-timeline but do speak position: sticky; will also see the effect, but simply without the scaling.

~

# In Closing

With those fine demos we conclude this second part of this series! We’ve covered how to create Scroll-Linked Animations based on the location of an element within the scroller, and how we can tweak their offsets. I think it’s pretty amazing what we can do with them … the amount of JavaScript that can be replaced with it will be huge.

I hope I’ve been able to get you excited for this possible future addition to CSS throughout this post. Although it still is in its very early stages, I’m confident this will become a CSS WG Recommendation one day 🙂

I’m glad to see that the Chromium engineers are actively working on this experimental implementation, taking the time to respond to newly reported bugs. I hope that other browser vendors will follow suit soon. Relevant tracking bugs to flag/star/follow:

• Chromium: https://bugs.chromium.org/p/chromium/issues/detail?id=1023424
• Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1676780
• Safari: https://bugs.webkit.org/show_bug.cgi?id=222295

~

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

🔥 The future of CSS: Scroll-Linked Animations (Part 2)

In this 2nd part covering @​scroll-timeline we turn things up a notch and dig into creating Scroll-Linked Animations using Element-based Offsets

🔗 https://t.co/OzatNnS48l#CSS #ScrollTimeline #animation pic.twitter.com/IIwaDHCEii

— Bram.us (@bramusblog) March 3, 2021

~