📜 Mastering @scroll-timeline in CSS

📌 What Is @scroll-timeline?

The @scroll-timeline at-rule is part of the newScroll-Linked Animations API. It allows animations to progress based on scroll position instead of time! 🚀
This enables smooth effects like parallax, progress indicators, reveal animations, and synchronized scrolling animations — all with pure CSS.

>>“With @scroll-Timeline, TimelineItem, the user becomes the timeline — scrolling drives the animation.”

🧩 Basic Syntax

Basic @scroll-timeline syntax

@scroll-timeline myTimeline {
  source: auto;
  orientation: block;
  scroll-offsets: 0%, 100%;
}

✔ You create a named timeline (e.g., myTimeline)
✔ Then attach it to animations using animation-timeline.

🎯 Core Properties of @scroll-timeline

PropertyDescription
sourceThe scroll container (default: viewport)
orientationblock (vertical) or inline (horizontal)
scroll-offsetsDefines animation progress points during scroll

🧪 Example: Fade in Element on Scroll

1️⃣ Define the Scroll Timeline

@scroll-timeline

@scroll-timeline fadeTimeline {
  source: auto;
  orientation: block;
  scroll-offsets: 0%, 100%;
}

2️⃣ Define Keyframes

@keyframes

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(40px); }
  to   { opacity: 1; transform: translateY(0); }
}

3️⃣ Apply Timeline to Animation

Connect animation to scroll

.item {
  animation-name: fadeIn;
  animation-duration: 1s; /* becomes irrelevant */
  animation-timeline: fadeTimeline;
  animation-range: 0% 100%;
}

✔ The animation now progresses as the user scrolls.
✔ No JavaScript needed.

🎬 Example: Horizontal Scroll Timeline

Horizontal scroll timeline

@scroll-timeline horizontalTimeline {
  source: auto;
  orientation: inline;
  scroll-offsets: 0px, 500px;
}

✔ Useful for horizontal carousels, galleries, or image comparisons.

🌟 Example: Progress Bar That Fills During Scroll

Progress bar scroll animation

@scroll-timeline progressTimeline {
  source: auto;
  orientation: block;
  scroll-offsets: 0%, 100%;
}

.progress-bar {
  animation: fillBar 1s linear;
  animation-timeline: progressTimeline;
  animation-range: 0% 100%;
}

@keyframes fillBar {
  from { width: 0%; }
  to   { width: 100%; }
}

✔ The progress bar fills exactly as the user scrolls down the page.

📦 Example: Parallax Scroll Effect

Parallax animation

@keyframes parallaxShift {
  from { transform: translateY(0); }
  to   { transform: translateY(-200px); }
}

@scroll-timeline parallaxTimeline {
  scroll-offsets: 0%, 100%;
}

.bg-layer {
  animation: parallaxShift 1s linear;
  animation-timeline: parallaxTimeline;
}

✔ Creates cinematic parallax movement based on scroll.

🧠 animation-range (Important!)

To control how much of the scroll should drive the animation:

animation-range

animation-range: entry 0% exit 100%;
  • entry → When element first enters viewport
  • exit → When element leaves

📘 Full Working Example

Full Scroll Animation

@scroll-timeline revealTimeline {
  source: auto;
  scroll-offsets: 0%, 100%;
}

@keyframes reveal {
  from { opacity: 0; transform: translateY(50px); }
  to   { opacity: 1; transform: translateY(0); }
}

.section {
  animation: reveal 1s ease-out;
  animation-timeline: revealTimeline;
  animation-range: entry 0% exit 100%;
}

✔ Smooth reveal as each section appears on screen.
✔ Fully native, no JS scroll listeners needed.

⚠️ Browser Support

  • ✔ Chrome 115+
  • ✔ Edge 115+
  • ❌ Safari (partially supported via flags)
  • ❌ Firefox (not supported yet)

Note

Always test scroll-linked animations on multiple browsers. Provide graceful fallbacks where necessary.

🧠 Best Practices

  • Use @scroll-timeline for performance — avoid JS scroll events
  • Don’t animate too many elements at once
  • Prefer transforms (GPU-friendly) over layout-changing properties
  • Use timelines for parallax, reveal effects, and progress bars

🔗 Helpful Resources

>>“Scroll-driven animations make interfaces feel alive — @scroll-timeline gives you native power with zero JavaScript.” ✨