Scroll-driven progress ring with animation-timeline in CSS

import { useEffect, useRef, useState } from "react";
import styles from "./Demo.module.scss";

/**
 * Whether the browser can drive the animation from scroll position itself.
 * Feature detection, not browser sniffing: the day Safari ships this, the
 * native path starts being used with no change here.
 */
const NATIVE_TIMELINE =
  typeof CSS !== "undefined" && CSS.supports("animation-timeline: scroll()");

export default function ScrollProgressRing() {
  const box = useRef<HTMLDivElement>(null);
  const [pct, setPct] = useState(0);

  useEffect(() => {
    const el = box.current;
    if (!el) return;

    // The percentage readout is text, so it is wired up either way. The
    // fallback below is the only part that also drives the ring.
    const onScroll = () => {
      const max = el.scrollHeight - el.clientHeight;
      const p = max > 0 ? el.scrollTop / max : 0;
      setPct(Math.round(p * 100));
      if (!NATIVE_TIMELINE) el.style.setProperty("--progress", String(p));
    };

    onScroll();
    el.addEventListener("scroll", onScroll, { passive: true });
    return () => el.removeEventListener("scroll", onScroll);
  }, []);

  return (
    <div className={styles.wrap}>
      <div
        ref={box}
        className={styles.scroller}
        tabIndex={0}
        role="region"
        aria-label="Scrollable sample content"
      >
        <div className={styles.inner}>
          {Array.from({ length: 8 }, (_, i) => (
            <p key={i} className={styles.line}>
              {i + 1}. Keep scrolling. The ring on the right is driven by this
              box, not by the page.
            </p>
          ))}
        </div>
      </div>

      <div className={styles.readout}>
        <svg className={styles.ring} viewBox="0 0 100 100" aria-hidden>
          <circle className={styles.track} cx="50" cy="50" r="42" />
          {/* pathLength normalises the geometry to 1, so dash values are plain
              fractions instead of 2 pi r worked out by hand. */}
          <circle
            className={styles.value}
            cx="50"
            cy="50"
            r="42"
            pathLength={1}
          />
        </svg>
        <p className={styles.pct}>
          {pct}%{" "}
          <span className={styles.mode}>
            {NATIVE_TIMELINE ? "scroll()" : "fallback"}
          </span>
        </p>
      </div>
    </div>
  );
}

.wrap {
  display: flex;
  align-items: center;
  gap: clamp(16px, 4vw, 32px);
  padding: clamp(20px, 4vw, 36px);

  /* Lets the ring, which is a sibling rather than a descendant of the
     scroller, see the timeline the scroller publishes. */
  timeline-scope: --lab-ring-scroll;

  /* Against the stage, not the viewport: this demo is a third of the width in
     the homepage strip and full width on its own page. */
  @container stage (max-width: 420px) {
    flex-direction: column;
    gap: 10px;
    padding: 14px;
  }
}

.scroller {
  flex: 1;
  min-width: 0;
  height: 190px;
  overflow-y: auto;
  overscroll-behavior: contain;
  border-radius: var(--r-md);
  border: 1px solid var(--line);
  background: var(--ink-850);

  /* Publishes this box's scroll position as a named timeline. Ignored by
     browsers that do not support scroll-driven animations. */
  scroll-timeline-name: --lab-ring-scroll;
  scroll-timeline-axis: block;
}

.inner {
  padding: 16px 18px;
  display: flex;
  flex-direction: column;
  gap: 14px;
}

.line {
  font-size: 14px;
  line-height: 1.6;
  color: var(--silver-300);
}

.readout {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 10px;
}

.ring {
  width: 96px;
  height: 96px;
  transform: rotate(-90deg); /* start the sweep at twelve o'clock */
}

/* Stacked, everything has to fit the stage's fixed height, so both the
   scroll box and the ring come down a size. */
@container stage (max-width: 420px) {
  .scroller {
    width: 100%;
    flex: none;
    height: 92px;
  }
  .inner {
    padding: 12px 14px;
    gap: 10px;
  }
  .line {
    font-size: 13px;
  }
  .ring {
    width: 56px;
    height: 56px;
  }
  .readout {
    flex-direction: row;
    align-items: center;
    gap: 12px;
  }
  .pct {
    flex-direction: row;
    align-items: baseline;
    gap: 8px;
  }
}

.track,
.value {
  fill: none;
  stroke-width: 7;
  stroke-linecap: round;
}

.track {
  stroke: var(--line);
}

.value {
  stroke: var(--accent, var(--mint));
  stroke-dasharray: 1;
  /* The fallback path: JavaScript writes --progress and this reads it. In a
     browser with scroll-driven animations the animation below wins, because
     animations outrank normal declarations in the cascade. */
  stroke-dashoffset: calc(1 - var(--progress, 0));
}

@keyframes ringFill {
  from {
    stroke-dashoffset: 1;
  }
  to {
    stroke-dashoffset: 0;
  }
}

@supports (animation-timeline: scroll()) {
  .value {
    animation-name: ringFill;
    animation-duration: auto; /* meaningless on a scroll timeline */
    animation-timing-function: linear;
    animation-fill-mode: both;
    animation-timeline: --lab-ring-scroll;
  }
}

.pct {
  font-family: var(--mono);
  font-size: 15px;
  color: var(--silver-050);
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 2px;
}

.mode {
  font-size: 10px;
  letter-spacing: 0.1em;
  text-transform: uppercase;
  color: var(--silver-500);
}