Skip to content

Commit 1c5888f

Browse files
Accept scroll() ranges as progress values only
rangeStart and rangeEnd are now numbers from 0 to 1, as elsewhere in the Motion API. The JS path uses them directly, and only the native path builds WAAPI percentage strings, so toPercentage and parsing them back are gone. Co-authored-by: Matt Perry <[email protected]>
1 parent 7bce891 commit 1c5888f

7 files changed

Lines changed: 37 additions & 44 deletions

File tree

‎dev/html/public/playwright/scroll/scroll-range.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,16 +48,16 @@
4848
*/
4949
const target = document.getElementById("target")
5050
const transition = { ease: "linear" }
51-
const targetRange = { target, rangeStart: "0%", rangeEnd: "50%" }
51+
const targetRange = { target, rangeStart: 0, rangeEnd: 0.5 }
5252

5353
const stops = [
5454
scroll(animate("#box", { opacity: [0, 1] }, transition), {
5555
rangeStart: 0.1,
5656
rangeEnd: 0.3,
5757
}),
5858
scroll(animate("#js-box", { x: [0, 100] }, transition), {
59-
rangeStart: "10%",
60-
rangeEnd: "30%",
59+
rangeStart: 0.1,
60+
rangeEnd: 0.3,
6161
}),
6262
scroll(
6363
animate("#target-box", { opacity: [0, 1] }, transition),

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ export const App = () => {
1515
const transition = { ease: "linear" } as const
1616
const targetRange = {
1717
target,
18-
rangeStart: "0%",
19-
rangeEnd: "50%",
18+
rangeStart: 0,
19+
rangeEnd: 0.5,
2020
} as const
2121

2222
const stops = [
@@ -25,8 +25,8 @@ export const App = () => {
2525
rangeEnd: 0.3,
2626
}),
2727
scroll(animate("#js-box", { x: [0, 100] }, transition), {
28-
rangeStart: "10%",
29-
rangeEnd: "30%",
28+
rangeStart: 0.1,
29+
rangeEnd: 0.3,
3030
}),
3131
scroll(
3232
animate("#target-box", { opacity: [0, 1] }, transition),

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33
* first keyframe before it and the last keyframe after it.
44
*
55
* Page height = 5 * 100vh, so with a 1000px viewport scrollLength = 4000px and
6-
* the page range 10%–30% is 400–1200px.
6+
* the page range 0.1–0.3 is 400–1200px.
77
*
88
* #target is 500px tall at top 2500px, so its cover range runs from scroll
99
* 1500px (top meets viewport bottom) to 3000px (bottom meets viewport top),
10-
* and the target range 0%–50% is 1500–2250px.
10+
* and the target range 0–0.5 is 1500–2250px.
1111
*
1212
* In browsers with ScrollTimeline, the opacity boxes run natively and the x
1313
* boxes via the JS observe path, so the two paths are checked against each

‎packages/framer-motion/src/render/dom/scroll/__tests__/range.test.ts‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -68,15 +68,15 @@ describe("scroll() rangeStart/rangeEnd", () => {
6868
})
6969

7070
/**
71-
* 25%–50% of the scroll range is 500–1000px.
71+
* Progress 0.25–0.5 of the scroll range is 500–1000px.
7272
*/
7373
test("Maps the range onto the animation and holds either side of it", async () => {
7474
const box = document.createElement("div")
7575
document.body.appendChild(box)
7676

7777
const stop = scroll(
7878
animate(box, { opacity: [0, 1], x: [0, 100] }, transition),
79-
{ rangeStart: "25%", rangeEnd: "50%" }
79+
{ rangeStart: 0.25, rangeEnd: 0.5 }
8080
)
8181

8282
const expectProgress = (opacity: string, transform: string) => {
@@ -109,7 +109,7 @@ describe("scroll() rangeStart/rangeEnd", () => {
109109
box.remove()
110110
})
111111

112-
test("Accepts fractions, and a range with only one end", async () => {
112+
test("Accepts a range with only one end", async () => {
113113
const start = document.createElement("div")
114114
const end = document.createElement("div")
115115
document.body.append(start, end)
@@ -139,12 +139,12 @@ describe("scroll() rangeStart/rangeEnd", () => {
139139
})
140140

141141
/**
142-
* With a target, native ViewTimeline resolves a plain percentage against
143-
* the timeline's cover range, so the JS path must too.
142+
* With a target, native ViewTimeline resolves a range against its cover
143+
* range, so the JS path must too.
144144
*
145145
* Target top = 1500, height = 500, viewport = 1000:
146146
* cover 0% = scroll 500, cover 100% = scroll 2000.
147-
* rangeStart "0%" → 500, rangeEnd "50%" → 1250.
147+
* rangeStart 0 → 500, rangeEnd 0.5 → 1250.
148148
*/
149149
test("With a target, the range is relative to the target's cover range", async () => {
150150
const target = document.createElement("div")
@@ -154,15 +154,15 @@ describe("scroll() rangeStart/rangeEnd", () => {
154154

155155
const stop = scroll(animate(target, { opacity: [0, 1] }, transition), {
156156
target,
157-
rangeStart: "0%",
158-
rangeEnd: "50%",
157+
rangeStart: 0,
158+
rangeEnd: 0.5,
159159
})
160160

161161
// Before the target enters the viewport.
162162
await fireScroll(200)
163163
expect(target.style.opacity).toBe("0")
164164

165-
// Cover 25% is halfway through the 0%–50% range.
165+
// Cover 25% is halfway through the 0–0.5 range.
166166
await fireScroll(875)
167167
expect(target.style.opacity).toBe("0.5")
168168

@@ -185,7 +185,7 @@ describe("scroll() rangeStart/rangeEnd", () => {
185185
const held = document.createElement("div")
186186
document.body.append(inRange, held)
187187

188-
const range = { rangeStart: "0%", rangeEnd: "50%" } as const
188+
const range = { rangeStart: 0, rangeEnd: 0.5 }
189189
const stopInRange = scroll(
190190
animate(inRange, { opacity: [0, 1] }, transition),
191191
range

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

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
11
import { AnimationPlaybackControls, observeTimeline } from "motion-dom"
22
import { clamp, progress } from "motion-utils"
3-
import { ScrollOptionsWithDefaults, ScrollRange } from "./types"
3+
import { ScrollOptionsWithDefaults } from "./types"
44
import { canUseNativeTimeline } from "./utils/can-use-native-timeline"
55
import { getTimeline } from "./utils/get-timeline"
66
import { offsetToViewTimelineRange } from "./utils/offset-to-range"
77

8-
const toPercentage = (value: ScrollRange) =>
9-
typeof value === "string" ? value : value * 100 + "%"
10-
118
export function attachToAnimation(
129
animation: AnimationPlaybackControls,
1310
options: ScrollOptionsWithDefaults
@@ -28,7 +25,7 @@ export function attachToAnimation(
2825
: canUseNativeTimeline()
2926

3027
/**
31-
* A range is a percentage of the whole timeline: the full scroll range,
28+
* A range is progress through the whole timeline: the full scroll range,
3229
* or for a target its "cover" range, from when the target starts to enter
3330
* the container until it has completely left. Native ScrollTimeline and
3431
* ViewTimeline already measure progress that way, but the JS fallback
@@ -49,27 +46,26 @@ export function attachToAnimation(
4946
: options
5047
)
5148

52-
const start = toPercentage(rangeStart ?? 0)
53-
const end = toPercentage(rangeEnd ?? 1)
49+
const start = rangeStart ?? 0
50+
const end = rangeEnd ?? 1
5451

5552
return animation.attachTimeline({
5653
timeline: useNative ? timeline : undefined,
5754
...(useNative &&
58-
(hasUserRange ? { rangeStart: start, rangeEnd: end } : range)),
55+
(hasUserRange
56+
? { rangeStart: start * 100 + "%", rangeEnd: end * 100 + "%" }
57+
: range)),
5958
observe: (valueAnimation) => {
6059
valueAnimation.pause()
6160

62-
const from = parseFloat(start)
63-
const to = parseFloat(end)
64-
6561
/**
6662
* Outside the range, hold the first or last keyframe, as native
6763
* animations do with their fill of "both".
6864
*/
6965
return observeTimeline((timelineProgress) => {
7066
valueAnimation.time =
7167
valueAnimation.iterationDuration *
72-
clamp(0, 1, progress(from, to, timelineProgress * 100))
68+
clamp(0, 1, progress(start, end, timelineProgress))
7369
}, timeline)
7470
},
7571
})

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

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,19 @@ export interface ScrollOptions {
55
axis?: "x" | "y"
66
offset?: ScrollOffset
77
/**
8-
* Where an animation starts, as a percentage (`"20%"`) or `0`–`1`
9-
* fraction of the scroll range, or of the target's cover range when
10-
* `target` is set, mirroring WAAPI `rangeStart`. Replaces `offset`.
11-
* Before it, the animation holds its first keyframe. Ignored by
12-
* callbacks.
8+
* Where an animation starts, as progress from `0` to `1` through the
9+
* scroll range, or through the target's cover range when `target` is
10+
* set. Replaces `offset`. Before it, the animation holds its first
11+
* keyframe. Ignored by callbacks.
1312
*/
14-
rangeStart?: ScrollRange
13+
rangeStart?: number
1514
/**
16-
* Where an animation ends, after `rangeStart`, mirroring WAAPI
17-
* `rangeEnd`. After it, the animation holds its last keyframe.
15+
* Where an animation ends, as progress from `0` to `1`, after
16+
* `rangeStart`. After it, the animation holds its last keyframe.
1817
*/
19-
rangeEnd?: ScrollRange
18+
rangeEnd?: number
2019
}
2120

22-
export type ScrollRange = number | `${number}%`
23-
2421
export interface ScrollOptionsWithDefaults extends ScrollOptions {
2522
axis: "x" | "y"
2623
container: Element

‎tests/scroll/scroll-range.spec.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ import { expect, Page, test } from "@playwright/test"
44
* scroll() rangeStart/rangeEnd map the range onto the animation and hold the
55
* first keyframe before it and the last keyframe after it.
66
*
7-
* With a 1000px viewport the page scrolls 4000px, so the page range 10%–30%
7+
* With a 1000px viewport the page scrolls 4000px, so the page range 0.1–0.3
88
* is 400–1200px. #target is 500px tall at top 2500px, so its cover range runs
9-
* from 1500px to 3000px and the target range 0%–50% is 1500–2250px.
9+
* from 1500px to 3000px and the target range 0–0.5 is 1500–2250px.
1010
*
1111
* Where ScrollTimeline is supported the opacity boxes run natively and the
1212
* x boxes via the JS observe path, so the two are checked against each other.

0 commit comments

Comments
 (0)