sticky-scroll-trigger 0.11.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -7
- package/dist/StickyScrollTrigger.d.ts +4 -1
- package/dist/StickyScrollTrigger.global.js +604 -121
- package/dist/StickyScrollTrigger.global.min.js +2 -2
- package/dist/StickyScrollTrigger.js +604 -121
- package/dist/StickyScrollTrigger.min.js +2 -2
- package/package.json +12 -12
package/README.md
CHANGED
|
@@ -40,7 +40,7 @@ npm install gsap sticky-scroll-trigger
|
|
|
40
40
|
For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
|
|
41
41
|
|
|
42
42
|
```html
|
|
43
|
-
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.
|
|
43
|
+
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.12.0/dist/StickyScrollTrigger.global.min.js"></script>
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
Consumers should only rely on the exports of `sticky-scroll-trigger` (or `window.StickyScrollTrigger` for the global build). The internal modules under `src/` are not part of the public API.
|
|
@@ -143,9 +143,10 @@ Avoid debounce logic that assumes it runs before GSAP's 200ms delay. Use `refres
|
|
|
143
143
|
|
|
144
144
|
Creates an instance that treats `root` (a selector string or `HTMLElement`) as the shared container. Everything documented below is an instance method on it, apart from the static [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances), which resolves a position across more than one instance. Throws if the shared container can't be found.
|
|
145
145
|
|
|
146
|
-
| option
|
|
147
|
-
|
|
|
148
|
-
| `scrollMarginTargets`
|
|
146
|
+
| option | default | description |
|
|
147
|
+
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
148
|
+
| `scrollMarginTargets` | `'[id]'` | Which elements inside the shared container get their `scroll-margin-top` kept in sync (see [Same-page links](#same-page-links)). `null` disables it entirely |
|
|
149
|
+
| `nestedStickyOptimization` | `'auto'` | Lays out sticky elements far from their range as `position: relative` (see [Nested sticky performance](#nested-sticky-performance)). `'auto'` turns it on only where the library expects a gain, `'always'` on every engine, `'off'` never |
|
|
149
150
|
|
|
150
151
|
Call them on the instance (`sticky.createStickyTrigger(...)`) rather than destructuring them out: a destructured method loses its `this` binding.
|
|
151
152
|
|
|
@@ -165,6 +166,8 @@ Registers a layer that pins a scene and advances its effect, and returns `Scroll
|
|
|
165
166
|
|
|
166
167
|
Nested Scene layers are accounted for automatically, so `pinnedContainer` isn't needed (see [End syntax](#end-syntax)).
|
|
167
168
|
|
|
169
|
+
`refreshPriority` passes through and still sets the order GSAP refreshes its triggers in, but no layer's window changes: this module works out every window, in the orders [End syntax](#end-syntax) describes, before GSAP refreshes any trigger.
|
|
170
|
+
|
|
168
171
|
You can specify `onKill`, `invalidateOnRefresh`, and `onRefreshInit`; the module also uses them internally. `invalidateOnRefresh` defaults to `true` (GSAP defaults to `false`) so function-valued tween props are re-measured on refresh, and an explicit value is respected. Freeze-window tracking is independent of the flag, so `invalidateOnRefresh: false` won't break it.
|
|
169
172
|
|
|
170
173
|
| option | default | description |
|
|
@@ -426,6 +429,22 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
426
429
|
- The default `'[id]'` covers everything a fragment link or `:target` can reach. Find-in-page and keyboard focus can scroll to arbitrary elements, which this doesn't cover; widen the selector if that matters to you
|
|
427
430
|
- To take this over yourself, pass `scrollMarginTargets: null` and compute positions with [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances) instead. Don't do both: a handler that reads `scroll-margin-top` and also applies `getScrollTop` would count the correction twice
|
|
428
431
|
|
|
432
|
+
## Nested sticky performance
|
|
433
|
+
|
|
434
|
+
Every Scene layer adds one level of nested `position:sticky`, and WebKit's layout cost grows about threefold per level: 9 levels take about 17ms of layout per frame in Safari, 11 levels over 100ms, and 16 can take seconds to load. Other engines don't slow down.
|
|
435
|
+
|
|
436
|
+
While the scroll is far from a sticky element's range, holding it there with `position:sticky` buys nothing, so the library lays it out as `position: relative` at the offset sticky would give it (top 0 before the range, its full travel after) and switches it back to sticky from a passive `scroll` listener before the range comes within reach. Nothing moves differently; the engine just lays out fewer sticky levels per frame. Only elements the library made sticky are switched: the Scene/Cover wrappers and `createStickyPin` triggers. A sticky element of your own is never switched (one around the library's elements is set to `static` for a moment at each `refresh()` to measure the layout, then gets its `style` attribute back as it was, two writes a `MutationObserver` on it sees), and everything is left alone when the shared container sits inside a scroll container or `body` scrolls the page instead of the window.
|
|
437
|
+
|
|
438
|
+
Which conditions turn it on is the library's call and may change between versions as engines change. Currently: WebKit (Safari, and every browser on iOS/iPadOS), for an instance whose sticky elements nest 7 or more levels deep, counting sticky elements of other instances or your own above them. Other engines are left untouched. Pass `'always'` to turn it on regardless, or `'off'` to never touch it.
|
|
439
|
+
|
|
440
|
+
GSAP measures every ScrollTrigger at scroll 0 inside its own refresh, so the switch shows it the layout for scroll 0 there and puts back the one for the current scroll before any `onRefresh` callback runs. Telling GSAP's refresh apart takes GSAP's `ScrollTrigger` class, which an instance picks up from the Vars it hands to `ScrollTrigger.create()`. On a page where no instance's Vars reach `ScrollTrigger.create()`, the switch stays off whatever the option says.
|
|
441
|
+
|
|
442
|
+
- A switched element also gets `z-index: 0` and `will-change: opacity` while relative, unless it already has its own, so it keeps the stacking context and composited layer sticky gave it
|
|
443
|
+
- A pin `trigger` with its own `left`, `right` or `bottom` stays sticky, and so does anything inside a sticky element of your own held by anything but a plain px or % `top` (one with no inset at all never sticks and doesn't count), anything under a transform, and anything whose parent is `display: contents` or inline
|
|
444
|
+
- An element whose content runs past the page's end (a pin range reaching the end, say) stays sticky past its range: moved down as `position: relative`, that content would make the page taller
|
|
445
|
+
- Content that changes size needs a `refresh()` anyway (see [Calling refresh](#calling-refresh)), and a window resize gets GSAP's own after a short delay; until then, a switched element stays at the offset measured at the last one
|
|
446
|
+
- A layout read in the same task as a programmatic scroll (`window.scrollTo()` followed by `getBoundingClientRect()`, say) sees the state for the previous scroll until the `scroll` event. Same-page links and `scrollIntoView()` land the same as with `'off'`
|
|
447
|
+
|
|
429
448
|
## Position syntax
|
|
430
449
|
|
|
431
450
|
`start` (and `end`'s position-clause form) accepts GSAP's standard `"element-side viewport-side"` syntax. With only one clause, the viewport side defaults to `top` (`"center"` is equivalent to `"center top"`, not `"center center"`). You can also pass a function that returns a string, or for the absolute scroll position case below, a number. It's re-evaluated on every `refresh()`, which is handy for reflecting variable values like header height.
|
|
@@ -507,10 +526,12 @@ An `end` on `trigger` itself counts the scenes nested inside `trigger` by the di
|
|
|
507
526
|
|
|
508
527
|
These rules assume the elements holding a scene's `trigger` grow with its spacer, as auto-height elements do under GSAP's pins. With a fixed CSS `height`, the spacer overflows the element instead, so GSAP's pins would move no point inside or after that element. This module still counts the scene as inside or above such points.
|
|
509
528
|
|
|
510
|
-
Counting an enclosing scene departs from plain GSAP pins, which measure a point inside a pinned element as if the pin weren't there, so whichever of `start` and `end` sits inside it lands early by the pin's duration unless `pinnedContainer` names that element. This module finds the nesting itself and counts an enclosing scene the way `pinnedContainer` does, but decides at each point rather than once at `start`, and for every enclosing scene rather than one. So it also counts a scene that freezes after `start` but before the point `end` names arrives, which `pinnedContainer` leaves out.
|
|
529
|
+
Counting an enclosing scene departs from plain GSAP pins, which measure a point inside a pinned element as if the pin weren't there, so whichever of `start` and `end` sits inside it lands early by the pin's duration unless `pinnedContainer` names that element. This module finds the nesting itself and counts an enclosing scene the way `pinnedContainer` does, but decides at each point rather than once at `start`, and for every enclosing scene rather than one. So it also counts a scene that freezes after `start` but before the point `end` names arrives, which `pinnedContainer` leaves out. The same goes for an `endTrigger` that is another Scene layer's `trigger`, which counts as enclosing itself. GSAP's `end` there lands early by that scene's dwell, and naming that element in `pinnedContainer` doesn't move it.
|
|
511
530
|
|
|
512
531
|
Some sets of Scene layers never settle on a layout where every `end` agrees with what it counts, such as two nested scenes whose `endTrigger`s each lie past the other's `trigger`. Others settle on one only because two ends each count the other's dwell, which GSAP's pins never do in any creation order: a pair whose ends count a share of each other would grow toward `1 / (1 - share)` times their own length. Others still settle on one no creation order gives: GSAP sizes a pin's spacer when that pin refreshes, so a scene refreshed first holds in the spacers added inside it later, yet one `end` can count a spacer through a scene's `trigger` while another counts that scene's dwell, which needs it refreshed first. The first two resolve the way GSAP's pins would if created in dependency order: each layer after the layers its `end` counts and after the scenes whose `trigger` encloses its own, in DOM order among layers that depend on each other. The third resolves the way they would if created in DOM order, close to the top-to-bottom order GSAP recommends creating them in. Either way, each `end` then counts only the layers before it, and a scene enclosed by an earlier one no longer pushes points outside that scene. If that order doesn't settle either, absolute starts and ends are read as each pin sees them when refreshed in that order.
|
|
513
532
|
|
|
533
|
+
A few rare layouts with nested Scene layers still end up with windows no creation order of GSAP's pins gives. This is a known limit with no fix planned. It happens when a layer whose window has shrunk to zero hides what another `end` depends on, when an enclosing scene delays both a `start` and its `end` by the same dwell, or, with an absolute `end` among ends that count each other, after falling back to one of the creation orders above. If a layer's window comes out a different length than you expect, write its `end` as a dwell (`'+='` and the length you want), which no other scene changes, and do the same for any layer whose length then changes. Giving every such layer the length GSAP's pins give when created top to bottom, each scene after the scenes nested inside it, usually takes one round. Rewriting only an absolute `end` isn't enough. A dwell doesn't follow later layout changes, though.
|
|
534
|
+
|
|
514
535
|
A `createOverlapScroll` cover layer's `end` instead counts a scene's dwell exactly when that scene freezes before the point arrives, for any `endTrigger` inside the container, registered or not: its window describes the rise on screen, and a cover has no pin spacer to match.
|
|
515
536
|
|
|
516
537
|
> Keep `createStickyTrigger`'s `endTrigger` inside the shared container: pointing at an element outside it throws. If you need to reference something outside the container, use a dwell distance (e.g. `'+=500'`) instead.
|
|
@@ -545,13 +566,14 @@ sticky.createOverlapScroll({
|
|
|
545
566
|
- GSAP's `clamp()` position wrapper isn't accepted, and a function-valued `start`/`end` is called with no arguments rather than with the `ScrollTrigger` instance GSAP passes (see [Position syntax](#position-syntax))
|
|
546
567
|
- A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can (see [End syntax](#end-syntax))
|
|
547
568
|
- If a Scene layer's `end` uses a position clause, don't set `endTrigger` to an element that gets pushed down by that same scene's own dwell; the value won't converge
|
|
548
|
-
- If Scene layers' `endTrigger`s depend on each other in a way that never settles, or only settles by counting each other's dwell or in a way no creation order gives, the layers resolve the way GSAP's pins would in one creation order (see [End syntax](#end-syntax)). `refresh()` throws only if that order doesn't settle either
|
|
549
569
|
- `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
|
|
570
|
+
- If Scene layers' `endTrigger`s depend on each other in a way that never settles, or only settles by counting each other's dwell or in a way no creation order gives, the layers resolve the way GSAP's pins would in one creation order (see [End syntax](#end-syntax)). `refresh()` throws only if that order doesn't settle either
|
|
571
|
+
- A few rare layouts with nested Scene layers still resolve to window lengths no creation order of GSAP's pins gives; writing the affected `end` as a dwell avoids it (see [End syntax](#end-syntax))
|
|
550
572
|
- Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
|
|
551
573
|
- You must call `refresh()` once manually after registration. Window resize/load recomputation is automatically wired to GSAP's own `refreshInit`, but for layout changes that don't involve those (e.g. content height changes), call `ScrollTrigger.refresh()` yourself (see [Calling refresh](#calling-refresh))
|
|
552
574
|
- Resizes from mobile browsers showing/hiding their address bar are absorbed automatically (see the repository's `ARCHITECTURE.md`, "Two-pass position measurement"), but other causes like `visualViewport` zoom are not handled
|
|
553
575
|
- `refresh()` writes an inline `scroll-margin-top` on every element matching `scrollMarginTargets` inside the shared container, and, on engines that drive the correction's ramps in CSS, adopts one stylesheet of its own per instance. That sheet is a constructed one, so a Content Security Policy needs no `style-src` exception for it. Both are undone by `destroy()`. Pass `scrollMarginTargets: null` to opt out (see [Same-page links](#same-page-links))
|
|
554
|
-
- Don't nest one `StickyScrollTrigger` instance's shared container inside another's
|
|
576
|
+
- Don't nest one `StickyScrollTrigger` instance's shared container inside another's. The inner instance's layers don't count the outer one's dwell, so their windows open too early by however much of that dwell comes before them, and a `refresh()` run while an outer layer is stuck shifts them again by a different amount. For a target inside both, [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances)'s ownership check also picks whichever instance is listed first. Give each instance its own part of the page instead
|
|
555
577
|
|
|
556
578
|
## License
|
|
557
579
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/*!
|
|
2
2
|
* @license
|
|
3
|
-
* StickyScrollTrigger v0.
|
|
3
|
+
* StickyScrollTrigger v0.12.0
|
|
4
4
|
* Copyright (c) 2026 Kuninori Ogino
|
|
5
5
|
* Released under the MIT License
|
|
6
6
|
* https://github.com/kuninori-ogino/sticky-scroll-trigger
|
|
@@ -43,6 +43,8 @@ export declare type EndValue = string | number;
|
|
|
43
43
|
|
|
44
44
|
declare const EXCLUDED_VAR_KEYS: readonly ["trigger", "start", "end", "endTrigger", "pin", "pinSpacing", "anticipatePin", "pinnedContainer", "pinReparent", "pinSpacer", "pinType", "horizontal", "scroller", "containerAnimation"];
|
|
45
45
|
|
|
46
|
+
export declare type NestedStickyOptimization = 'auto' | 'always' | 'off';
|
|
47
|
+
|
|
46
48
|
declare type PassThroughVars = Omit<ScrollTrigger.Vars, typeof EXCLUDED_VAR_KEYS[number]>;
|
|
47
49
|
|
|
48
50
|
export declare type PositionInput = PositionValue | (() => PositionValue);
|
|
@@ -65,6 +67,7 @@ export default StickyScrollTrigger;
|
|
|
65
67
|
|
|
66
68
|
export declare interface StickyScrollTriggerOptions {
|
|
67
69
|
scrollMarginTargets?: string | null;
|
|
70
|
+
nestedStickyOptimization?: NestedStickyOptimization;
|
|
68
71
|
}
|
|
69
72
|
|
|
70
73
|
export { }
|