Add rangeStart/rangeEnd support for scroll() (re-attempt of #3646)

dev/react/src/tests/scroll-range-with-offset.tsx

@@ -0,0 +1,38 @@
+import { animate, scroll } from "framer-motion"
+import * as React from "react"
+import { useEffect } from "react"
+
+export const App = () => {
+    useEffect(() => {
+        const box = document.getElementById("box")!
+
+        const animation = animate(box, {
+            opacity: [0, 0.5],
+        })
+
+        const stop = scroll(animation, {
+            rangeStart: "0%",
+            rangeEnd: "20%",
+            offset: ["0%", "20%"],
+        })
+
+        return () => stop()
+    }, [])
+
+    return (
+        <>
+            <div style={{ height: "500vh" }} />
+            <div
+                id="box"
+                style={{
+                    position: "fixed",
+                    top: 0,
+                    left: 0,
+                    width: 100,
+                    height: 100,
+                    backgroundColor: "red",
+                }}
+            />
+        </>
+    )
+}

dev/react/src/tests/scroll-range.tsx

@@ -0,0 +1,37 @@
+import { animate, scroll } from "framer-motion"
+import * as React from "react"
+import { useEffect } from "react"
+
+export const App = () => {
+    useEffect(() => {
+        const box = document.getElementById("box")!
+
+        const animation = animate(box, {
+            opacity: [0, 0.5],
+        })
+
+        const stop = scroll(animation, {
+            rangeStart: "0%",
+            rangeEnd: "20%",
+        })
+
+        return () => stop()
+    }, [])
+
+    return (
+        <>
+            <div style={{ height: "500vh" }} />
+            <div
+                id="box"
+                style={{
+                    position: "fixed",
+                    top: 0,
+                    left: 0,
+                    width: 100,
+                    height: 100,
+                    backgroundColor: "red",
+                }}
+            />
+        </>
+    )
+}

packages/framer-motion/cypress/integration/scroll-range.ts

@@ -0,0 +1,55 @@
+describe("scroll() rangeStart/rangeEnd", () => {
+    it("Animation is inactive after rangeEnd", () => {
+        cy.visit("?test=scroll-range")
+            .wait(100)
+            .viewport(100, 400)
+
+        // Scroll to ~50% (well past the 20% rangeEnd)
+        cy.scrollTo(0, 800)
+            .wait(200)
+            .get("#box")
+            .then(([$element]: any) => {
+                const opacity = parseFloat(
+                    getComputedStyle($element).opacity
+                )
+
+                if ((window as any).ScrollTimeline) {
+                    // With native ScrollTimeline + rangeStart/rangeEnd + fill: auto,
+                    // animation is inactive after 20% scroll. Opacity reverts to
+                    // CSS default (1).
+                    expect(opacity).to.equal(1)
+                } else {
+                    // Without native ScrollTimeline, rangeStart/rangeEnd have no
+                    // effect. Animation maps full scroll to progress, so at 50%
+                    // scroll opacity = 0.25 (50% of 0 to 0.5).
+                    expect(opacity).to.equal(0.25)
+                }
+            })
+    })
+
+    it("Honors offset in the JS fallback when combined with rangeStart/rangeEnd", () => {
+        cy.visit("?test=scroll-range-with-offset")
+            .wait(100)
+            .viewport(100, 400)
+
+        // Scroll to ~50% (well past the 20% rangeEnd / offset end)
+        cy.scrollTo(0, 800)
+            .wait(200)
+            .get("#box")
+            .then(([$element]: any) => {
+                const opacity = parseFloat(
+                    getComputedStyle($element).opacity
+                )
+
+                if ((window as any).ScrollTimeline) {
+                    // Native path: rangeStart/rangeEnd + fill: "auto" → inactive
+                    // after the range; opacity reverts to CSS default (1).
+                    expect(opacity).to.equal(1)
+                } else {
+                    // JS fallback path: offset clamps progress to 1 past the
+                    // range, so the animation rests at its end keyframe (0.5).
+                    expect(opacity).to.equal(0.5)
+                }
+            })
+    })
+})

packages/framer-motion/src/render/dom/scroll/attach-animation.ts

@@ -10,6 +10,8 @@ export function attachToAnimation(
 ) {
     const timeline = getTimeline(options)
 
+    const hasUserRange = options.rangeStart || options.rangeEnd
+
     const range = options.target
         ? offsetToViewTimelineRange(options.offset)
         : undefined
@@ -26,11 +28,17 @@ export function attachToAnimation(
 
     return animation.attachTimeline({
         timeline: useNative ? timeline : undefined,
-        ...(range &&
-            useNative && {
-                rangeStart: range.rangeStart,
-                rangeEnd: range.rangeEnd,
-            }),
+        ...(hasUserRange
+            ? {
+                  rangeStart: options.rangeStart,
+                  rangeEnd: options.rangeEnd,
+                  fill: "auto",
+              }
+            : range &&
+              useNative && {
+                  rangeStart: range.rangeStart,
+                  rangeEnd: range.rangeEnd,
+              }),
         observe: (valueAnimation) => {
             valueAnimation.pause()
 

packages/framer-motion/src/render/dom/scroll/types.ts

@@ -6,6 +6,8 @@ export interface ScrollOptions {
     target?: Element
     axis?: "x" | "y"
     offset?: ScrollOffset
+    rangeStart?: string
+    rangeEnd?: string
 }
 
 export interface ScrollOptionsWithDefaults extends ScrollOptions {

packages/motion-dom/src/animation/NativeAnimation.ts

@@ -250,6 +250,7 @@ export class NativeAnimation<T extends AnyResolvedKeyframe>
         timeline,
         rangeStart,
         rangeEnd,
+        fill,
         observe,
     }: TimelineWithFallback): VoidFunction {
         if (this.allowFlatten) {
@@ -263,6 +264,7 @@ export class NativeAnimation<T extends AnyResolvedKeyframe>
 
             if (rangeStart) (this.animation as any).rangeStart = rangeStart
             if (rangeEnd) (this.animation as any).rangeEnd = rangeEnd
+            if (fill) this.animation.effect?.updateTiming({ fill } as any)
 
             return noop<void>
         } else {

packages/motion-dom/src/animation/types.ts

@@ -25,6 +25,7 @@ export interface TimelineWithFallback {
     timeline?: ProgressTimeline
     rangeStart?: string
     rangeEnd?: string
+    fill?: string
     observe: (animation: AnimationPlaybackControls) => VoidFunction
 }