CSS animation-timeline Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The animation-timeline CSS property allows developers to control which timeline an animation should follow. In essence, it decouples an animation from the default document timeline, enabling it to be synchronized with custom timelines or other scroll- or view-based progressions. This gives designers and developers the ability to create animations that react dynamically to user interaction, such as scrolling or media playback, rather than running on a fixed schedule. By assigning an animation to a specific timeline, the progression of keyframes can be influenced by that timeline’s state, offering far more granular control over how and when visual changes occur.

One of the primary use cases for animation-timeline is combining it with scroll-driven or view-based animations. For example, pairing it with a scroll-timeline allows animations to progress in sync with the user’s scroll position, producing effects like parallax movement, element reveals, or synchronized transitions. Unlike the standard animation-delay, which offsets an animation by a set duration, animation-timeline links the animation’s playback to an external source of time, meaning the animation can pause, reverse, or accelerate depending on the timeline’s state. This provides designers with a much richer vocabulary for expressing motion and interactivity.

Beyond scroll interactions, animation-timeline also facilitates synchronization across multiple elements. Animations that are tied to the same custom timeline will progress in unison, regardless of when they are triggered, creating cohesive, coordinated effects without relying on individual animation-duration calculations. This makes it easier to maintain complex sequences or layered animations without constantly adjusting timing values manually. As web experiences increasingly demand responsive, dynamic visuals, animation-timeline represents a powerful tool for crafting animations that feel connected to user behavior and environmental context rather than existing in isolation.

Definition

Initial value: auto
Applies to: all elements
Inherited: no
Computed value: a list, each item either a case-sensitive CSS identifier or the keywords none, auto
Animatable: no
JavaScript syntax: object.style.animationTimeline

Syntax

animation-timeline: none | <timeline-name> | auto;

Values

noneThe animation is not linked to any timeline.
<timeline-name>Links the animation to a named timeline created using <@scroll-timeline> or <@view-timeline>.
autoThe browser automatically determines the timeline to use. Usually equivalent to linking the animation to the element’s scroll-linked timeline if used inside a view-timeline.

Example

HTML

<div class="scroller" id="scroller">

  <section class="spacer">

    <h1>Scroll to animate</h1>

  </section>



  <section class="panel">

    <div class="animated">Scroll‑linked</div>

  </section>



  <section class="spacer">

    <p>Keep scrolling</p>

  </section>

</div>

CSS

/* Base styles */
:root {
  --panel-height: 60vh;
}
* {
  box-sizing: border-box;
}
html, body {
  height: 100%;
  margin: 0;
  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial;
  background: #0f172a;
  color: #e6edf3;
}

.scroller {
  height: 100%;
  overflow-y: auto;
  scroll-behavior: smooth;
}

/* Define a scroll timeline tied to the scroller element */
@scroll-timeline scroller-timeline {
  source: selector(#scroller);
  orientation: block;
  scroll-offsets: 0% 100%;
}

/* Keyframes for the animation */
@keyframes grow-rotate {
  0% {
    transform: translateY(0) scale(0.6) rotate(0deg);
    opacity: 0.3;
    border-radius: 40px;
  }
  50% {
    transform: translateY(-8vh) scale(1) rotate(180deg);
    opacity: 0.9;
    border-radius: 12px;
  }
  100% {
    transform: translateY(-16vh) scale(1.2) rotate(360deg);
    opacity: 1;
    border-radius: 20px;
  }
}

/* Layout */
.spacer {
  height: calc((100vh - var(--panel-height)) / 2);
  display: grid;
  place-items: center;
  background: linear-gradient(180deg, rgba(255,255,255,0.02), transparent);
  color: #cbd5e1;
}

.panel {
  height: var(--panel-height);
  display: grid;
  place-items: center;
}

/* Animated element uses the scroll timeline */
.animated {
  width: 180px;
  height: 180px;
  background: linear-gradient(135deg, #06b6d4, #7c3aed);
  display: grid;
  place-items: center;
  color: white;
  font-weight: 700;
  box-shadow: 0 10px 30px rgba(2,6,23,0.6);

  animation-name: grow-rotate;
  animation-duration: 1s;
  animation-timeline: scroller-timeline;
  animation-fill-mode: both;
  animation-timing-function: linear;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS animation-timeline property. Hover over a browser icon to see the version that first introduced support for this CSS property.