sticky-scroll-trigger 0.10.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 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.10.0/dist/StickyScrollTrigger.global.min.js"></script>
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 | 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 |
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 |
@@ -282,7 +285,7 @@ sticky.refresh();
282
285
 
283
286
  Here `start` means only where the element sits while pinned, not when pinning begins, as it does for the other methods. Pinning begins the moment `trigger` reaches that position naturally, which is CSS's decision rather than a separate number to set, so a pin's position and the scroll position it engages at are one setting.
284
287
 
285
- That's why `start` throws on an [absolute scroll position](#absolute-scroll-position) (`start: 20`, which GSAP reads as scroll position 20) instead of silently treating it as a px distance. `top` is its own option for the same reason: with the bare-number slot reserved for GSAP's meaning, `'top 20px'` would otherwise be a pin's only way to say "20px below the top of the viewport". `end` does take an absolute scroll position (`end: 3000` releases at scroll 3000), since a release point is a real thing to ask for on the scroll axis.
288
+ That's why `start` throws on an [absolute scroll position](#absolute-scroll-position) (`start: 20`, which GSAP reads as scroll position 20) instead of silently treating it as a px distance. `top` is its own option for the same reason: with the bare-number slot reserved for GSAP's meaning, `'top 20px'` would otherwise be a pin's only way to say "20px below the top of the viewport". `end` does take an absolute scroll position (`end: 3000` releases at scroll 3000), since a release point is a real thing to ask for on the scroll axis. If scroll 3000 falls inside a Scene layer's freeze, a pin inside the shared container holds until that freeze ends. Pinning also starts only after the dwell of every scene that freezes first, so the pin can hold for less scroll than GSAP's, or not at all, as with a Scene layer's [absolute `end`](#absolute-scroll-position).
286
289
 
287
290
  Clauses resolve exactly as they do elsewhere, including the one-token forms that name the element's own side: `'top 20px'` puts the element's top 20px below the viewport's top edge, while `'20px'` puts it 20px above.
288
291
 
@@ -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.
@@ -460,6 +479,10 @@ GSAP treats a value as an absolute scroll position rather than a clause whenever
460
479
 
461
480
  `start: '500'` (or `start: 500`) freezes starting at absolute scroll position 500px, ignoring the trigger's natural position and any preceding dwell. `end: '500'` ends the freeze window at 500px the same way, clamped to `start` if that would put `end` before it, matching GSAP's own `end = Math.max(start, ...)`.
462
481
 
482
+ When an absolute `start` falls inside another Scene layer's freeze window, the reported window (what GSAP gets, and so `self.start`/`self.end` and callbacks) keeps the written `start` and its length, as GSAP's own pins overlap. The page itself can't freeze twice at once, so it freezes only for the part of that window the other scene hasn't already frozen; positions (`resolveScrollPosition`, same-page links, cover layers and pins) follow the page.
483
+
484
+ An absolute `end` can give a Scene layer's window a different length than GSAP's pin. A position-clause `start` waits out the dwell of every scene that freezes first, including one enclosing `trigger`, one inside it, or one later in the DOM, while GSAP's pin starts after the spacers already placed above it. The wait doesn't change the length of a dwell or position-clause `end`, which is measured from that start, but an absolute one stays at the written value, so the window is shorter by however much later it starts than GSAP's, down to zero once the start passes the end. GSAP's `pinnedContainer` also delays the start for an enclosing scene, but moves an absolute `end` along with it. A scene above `trigger` that freezes later doesn't delay the start, which can make the window longer, as GSAP's pins created in another order would give. An absolute `start` doesn't wait, so with an absolute `end` the window keeps the written length.
485
+
463
486
  `'500 top'` (two tokens) and `'500px'` (a suffix) don't qualify; they resolve as offsets via the bare-number row in the table above, same as GSAP.
464
487
 
465
488
  > [`createOverlapScroll`](#createoverlapscrolloptions)'s `start` doesn't support absolute scroll positions: a cover layer's sticky position is always computed relative to its own wrapper (see the repository's `ARCHITECTURE.md`), which has no equivalent for one. It throws instead; use a position clause.
@@ -503,9 +526,11 @@ An `end` on `trigger` itself counts the scenes nested inside `trigger` by the di
503
526
 
504
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.
505
528
 
506
- 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.
530
+
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.
507
532
 
508
- Some sets of Scene layers have no layout where every `end` agrees with what it counts, such as two nested scenes whose `endTrigger`s each lie past the other's `trigger`. Those 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. Each `end` then counts only the layers before it, and a scene enclosed by an earlier one no longer pushes points outside that scene.
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.
509
534
 
510
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.
511
536
 
@@ -541,13 +566,14 @@ sticky.createOverlapScroll({
541
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))
542
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))
543
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
544
- - If Scene layers' `endTrigger`s depend on each other in a way that never settles, the layers resolve in dependency order (see [End syntax](#end-syntax)). `refresh()` can still throw in rare arrangements, such as a scene whose `end` counts one with an absolute `start` only while a third scene's window closes before it, and that third scene's `start` moves with the first scene's dwell. Two layers whose ends each move the other settle on the one answer they share
545
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))
546
572
  - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
547
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))
548
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
549
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))
550
- - Don't nest one `StickyScrollTrigger` instance's shared container inside another's: once a target sits inside more than one, [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances)'s ownership check picks whichever instance is listed first, and neither instance's own dwell alone is actually correct for it
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
551
577
 
552
578
  ## License
553
579
 
@@ -1,6 +1,6 @@
1
1
  /*!
2
2
  * @license
3
- * StickyScrollTrigger v0.10.0
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 { }