usecueweb development

Staggered animation by Usecue

Close
  • readme.txt
  • index.html
  • stagger.css
  • stagger.js

What is this?

A tiny helper for staggered (or chained) animations: the children of an element enter one after the other. The trick is a CSS animation with a delay per child, like style="--d: 150ms;", style="--d: 300ms;", … Setting these by hand works, but is a pain. This script does it for you, in 45 lines of vanilla JS.

How to use it?

Give any container the class stagger and load the CSS and JS from this demo, the script at the end of the body.

<ul class="stagger">
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
</ul>
<link rel="stylesheet" href="stagger.css" />
<script src="stagger.js"></script>

The timing (the delay before the first child and the step between two children) can be set in the top of the stagger.js file.

Features

The stagger is only for what is on the screen at load. All those children form one queue: when a page has two stagger containers, the second one starts where the first one left off, instead of at the same time. The children outside the screen are simply there, without animation: nothing is hidden, so nobody has to wait for content while scrolling. Once the visitor scrolls, the children that are still waiting all start at once. A scroll by the visitor is recognised by the input that causes it (wheel, touch, keys, the scroll bar), so a scroll by the browser does not count. A reload halfway down the page staggers what is on the screen there: the script restores the scroll position itself, before it looks at what is on the screen. Without JS, there is no animation and everything is simply there. Visitors who prefer reduced motion get no animation at all.

Want something more radical? This CSS-only version sets a number per child in the HTML and needs no JS at all.

License

This code is licensed WTFPL.

 1<div class="page">
 2    <div class="stagger">
 3        <h1>Stagger Demo</h1>
 4        <p>Every child of a stagger container enters a little after the one before. The cards are a second container: they start where the text left off.</p>
 5    </div>
 6    <ul class="stagger cards">
 7        <li>1</li>
 8        <li>2</li>
 9        <li>3</li>
10        <li>4</li>
11        <li>5</li>
12        <li>6</li>
13    </ul>
14    <p>Scroll down while the cards are still entering: the ones that are still waiting all start at once. <a href="javascript:window.location.reload();">Replay animation</a></p>
15</div>
16<div class="page">
17    <h2>Outside the screen at load</h2>
18    <p>These cards were below the fold, so they are simply there. Nobody wants to wait for content while scrolling.</p>
19    <ul class="stagger cards">
20        <li>1</li>
21        <li>2</li>
22        <li>3</li>
23        <li>4</li>
24        <li>5</li>
25        <li>6</li>
26    </ul>
27    <p><a href="javascript:window.location.reload();">Replay animation</a></p>
28</div>
29<link rel="stylesheet" href="/demos/stagger/stagger.css" />
30<script src="/demos/stagger/stagger.js"></script>
 1@keyframes stagger-in {
 2    from {opacity: 0; transform: translateY(1.5rem);}
 3}
 4/* on the screen at load (set by stagger.js) */
 5.stagger > .enter {
 6    animation: stagger-in .6s cubic-bezier(.2,.7,.2,1) backwards;
 7    animation-delay: var(--d, 0ms);
 8}
 9@media (prefers-reduced-motion: reduce) {
10    .stagger > .enter {animation: none;}
11}
12
13/* CSS for demo layout only */
14.page {
15    display: flex;
16    min-height: 95vh;
17    flex-direction: column;
18    justify-content: center;
19    max-width: 30rem;
20    margin-inline: auto;
21}
22.cards {
23    display: grid;
24    grid-template-columns: repeat(3, 1fr);
25    gap: 1rem;
26    padding: 0;
27    list-style: none;
28}
29.cards li {
30    background: #f2f2f2;
31    border-radius: .5rem;
32    padding: 1.5rem 1rem;
33    text-align: center;
34    font-weight: 600;
35}
 1const staggerSelector = '.stagger > *'; //elements that enter one after the other
 2const staggerDelay = 100; //delay before the first element in ms
 3const staggerStep = 150; //time between two elements in ms
 4
 5//restore the scroll position on a reload (and back/forward) right away, so we know
 6//what is on the screen; the browser would do it later, which would count as a scroll
 7const staggerKey = 'scroll:' + location.pathname;
 8history.scrollRestoration = 'manual';
 9window.addEventListener('pagehide', function() {
10    try { sessionStorage.setItem(staggerKey, window.scrollY); } catch (e) {}
11});
12try {
13    const y = sessionStorage.getItem(staggerKey);
14    const navigation = performance.getEntriesByType('navigation')[0];
15    if (y && navigation && (navigation.type === 'reload' || navigation.type === 'back_forward')) {
16        window.scrollTo({top: +y, behavior: 'instant'});
17    }
18} catch (e) {}
19
20//at load, the elements on the screen enter one after the other (also in the next
21//container); the elements outside the screen are simply there
22let staggerTime = performance.now() + staggerDelay;
23const staggerQueue = [];
24document.querySelectorAll(staggerSelector).forEach(function(element) {
25    const rect = element.getBoundingClientRect();
26    if (rect.bottom <= 0 || rect.top >= window.innerHeight) return;
27    element.style.setProperty('--d', Math.round(staggerTime - performance.now()) + 'ms');
28    element.classList.add('enter');
29    staggerQueue.push({element: element, time: staggerTime});
30    staggerTime += staggerStep;
31});
32//once the visitor scrolls, the elements that are still waiting all start at once;
33//a scroll by the visitor is recognised by the input that causes it (wheel, touch,
34//keys, the scroll bar), so a scroll by the browser does not count
35const staggerInput = ['wheel', 'touchmove', 'keydown', 'mousedown'];
36const staggerKeys = ['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '];
37function staggerFlush(event) {
38    if (event.type === 'keydown' && (staggerKeys.indexOf(event.key) < 0 || event.target.closest('input, textarea, select'))) return;
39    const now = performance.now();
40    staggerQueue.forEach(function(item) {
41        if (item.time > now) item.element.style.setProperty('--d', '0ms');
42    });
43    staggerInput.forEach(function(type) {
44        window.removeEventListener(type, staggerFlush);
45    });
46}
47staggerInput.forEach(function(type) {
48    window.addEventListener(type, staggerFlush, {passive: true});
49});