sticky-scroll-trigger 0.12.0 → 0.14.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.12.0/dist/StickyScrollTrigger.global.min.js"></script>
43
+ <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.14.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.
@@ -170,6 +170,8 @@ Nested Scene layers are accounted for automatically, so `pinnedContainer` isn't
170
170
 
171
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.
172
172
 
173
+ Inside GSAP's own refresh, a layer's `onRefreshInit` runs `refresh()` again only when that layer has its own callback or the DOM has changed since the last run. A change another listener makes between the layers through a variable or a stylesheet's rules alone shows in the next refresh.
174
+
173
175
  | option | default | description |
174
176
  | ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
175
177
  | `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise |
@@ -392,16 +394,22 @@ An `element` outside every given instance's shared container is measured directl
392
394
 
393
395
  Recomputes each layer's sticky `top`, dwell spacer height, and freeze window (`start`/`end`). It also rebuilds nested DOM when triggers are added, removed, or reordered. If nothing has changed, it does not rebuild.
394
396
 
395
- Kill-driven teardown/rebuild is deferred to a microtask and coalesced per task. This DOM move can reload `<iframe>` elements or drop focus for focused inputs inside the managed container. This behavior runs on every kill or relevant layout change and cannot be disabled, so be careful when placing iframes or focus-sensitive inputs under the controller.
397
+ Kill-driven teardown/rebuild is deferred to a microtask, or to a GSAP refresh later in the same task, and coalesced per task. While the page scrolls, it waits for the scroll to stop, as GSAP's own refresh does. This DOM move can reload `<iframe>` elements or drop focus for focused inputs inside the managed container. This behavior runs on every kill or relevant layout change and cannot be disabled, so be careful when placing iframes or focus-sensitive inputs under the controller.
398
+
399
+ A killed `createOverlapScroll` layer's wrapper, which holds `trigger` and every sibling before it, comes off during the kill instead, so the iframe and focus effects there happen then. Code later in the same task (the next breakpoint's `gsap.matchMedia()` setup, say) finds `trigger` back among those siblings, unless another overlap in the same parent still wraps it. Scene layers' teardown and rebuild still wait for the microtask or a GSAP refresh in the same task, unless the kill leaves the instance with no layer or pin: then everything it put on the page comes off during the kill, or once the scroll stops if the page is scrolling (see [`destroy()`](#destroy)).
396
400
 
397
401
  If surviving layers' freeze windows change after kill, GSAP's cached `start`/`end` values are synced internally.
398
402
 
403
+ A kill keeps the content on screen where it is: the scroll position takes up the dwell that comes out. `kill(false)` and `once: true` remove a layer the same way `kill()` does, so GSAP's pin spacer isn't left behind and scrolling back up shows no gap where the dwell was.
404
+
399
405
  ### `destroy()`
400
406
 
401
407
  Tears down the controller, restores the original DOM layout, and reverts z-order changes from `createOverlapScroll`. This is also the only entry point that can clean up cover layers that were never passed to `ScrollTrigger.create()`.
402
408
 
403
409
  It only cleans up DOM/styles managed by this module. You still need to kill active ScrollTrigger instances yourself. After `destroy()`, `createStickyTrigger`, `createOverlapScroll` and `createStickyPin` throw and `refresh()` is a no-op. Calling `destroy()` twice is safe.
404
410
 
411
+ Killing an instance's last layer or pin hands the page back the same way, `scroll-margin-top` and `scroll` listeners included, without destroying it: the next registration puts it back to work. So an instance created in each `gsap.matchMedia()` setup needs no `destroy()` in the setup's cleanup, as long as every layer and pin it returns goes to `ScrollTrigger.create()`.
412
+
405
413
  ## Same-page links
406
414
 
407
415
  Pinning decouples an element's position in the document from the scroll position at which it actually reaches the top of the viewport. The browser's own "scroll an element into view" is a single calculation made from the current layout, so on its own it lands short by the dwell of every scene that freezes before the element gets there. This is true of any pinning technique, GSAP's own `pin` included.
@@ -445,6 +453,29 @@ GSAP measures every ScrollTrigger at scroll 0 inside its own refresh, so the swi
445
453
  - 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
454
  - 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
455
 
456
+ ### GPU memory of stacked covers
457
+
458
+ A browser can keep rendering a stuck layer after its cover has hidden it, each covered layer on screen holding about a viewport's worth of rendered pixels in GPU memory. Overlap layers in a row, each layer's `cover` being the next one's `trigger`, nest inside each other, so every earlier layer of the row stays stuck on screen until the row ends, and the memory can grow with its length. Past the GPU memory budget, parts of the viewport can go blank while scrolling.
459
+
460
+ To keep it down, split a long row into short ones, each wrapped in an element of its own. A row's layers are released when its wrapper's bottom edge arrives, and scroll out together:
461
+
462
+ ```html
463
+ <div class="container__inner">
464
+ <div>
465
+ <section>...</section>
466
+ <section>...</section>
467
+ <section>...</section>
468
+ </div>
469
+ <div>
470
+ <section>...</section>
471
+ <section>...</section>
472
+ <section>...</section>
473
+ </div>
474
+ </div>
475
+ ```
476
+
477
+ Between two rows the page scrolls normally instead of covering, and each row's last section needs [the room](#room-for-the-rise) its rise takes.
478
+
448
479
  ## Position syntax
449
480
 
450
481
  `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.
@@ -473,6 +504,13 @@ The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start:
473
504
 
474
505
  GSAP passes the `ScrollTrigger` instance to its own function-valued `start`/`end` (`start: (self) => ...`), and this module doesn't, so a function declaring that parameter is a TypeScript error. There is nothing to pass: this module's `refresh()` resolves these functions, and it runs whether or not the returned `ScrollTrigger.Vars` was ever handed to `ScrollTrigger.create()`. `self.start`/`self.end` would be circular anyway, since the freeze window they report is what `refresh()` is in the middle of computing.
475
506
 
507
+ A [`createStickyTrigger`](#createstickytriggeroptions) `end` function can read the layout, as a GSAP pin's can: where an element sits, or the page's height. GSAP calls a pin's `end` with the spacers of the pins before it in place and those after it taken out. So when the function returns a dwell or an absolute position, `refresh()` calls it again in that layout: the dwell of the instance's earlier layers in place right after their triggers, and the dwell of its own layers and of every instance further down the page taken out. Page order stands in for GSAP's creation order, so this matches pins created top to bottom. What differs from GSAP:
508
+
509
+ - The function runs once or twice more per `refresh()` (at most six times more). Meanwhile the page is shorter and holds an empty `div` after each earlier trigger, which a `MutationObserver` sees. If the shorter page cut the scroll back, `refresh()` scrolls back. Firefox and Safari can fire one `scroll` event during such a `refresh()`, with the scroll where it was
510
+ - That `div` is a box of its own, where GSAP's pin-spacer takes the trigger's place. A position below it comes out later by the trigger's bottom margin when that margin collapses with the next element's top margin, or by the gap in a grid or flex layout
511
+ - [`resolveScrollPosition`](#resolvescrollpositionelement-position) called from the function measures the page `refresh()` left, as anywhere else, so a function built on it returns what it did before
512
+ - From the first `onRefreshInit` of any instance's layer or pin handed to `ScrollTrigger.create()` on, a `ScrollTrigger.refresh()` from the function measures the page and the scroll `refresh()` left, and what the function returns counts as it would without that call. A `refreshInit` callback GSAP calls before that one sees the function's layout and the scroll as that layout left it. With no layer or pin of any instance handed over, GSAP measures every ScrollTrigger in that layout and runs their callbacks at the scroll that layout left
513
+
476
514
  ### Absolute scroll position
477
515
 
478
516
  GSAP treats a value as an absolute scroll position rather than a clause whenever it's just a number: a plain JS number, or a string `Number()` converts on its own with no keyword, second token, or `%`/`px` suffix, `'-50'` and `'1e3'` included. It ignores the reference element entirely in that case (`ScrollTrigger.js`'s `_parsePosition`: `isNaN(value) || (value = +value)`). This module follows the same rule for `start` and `end`, and for [`createStickyPin`](#createstickypinoptions)'s `end`, [`createResolvedTrigger`](#createresolvedtriggeroptions)'s `start`/`end`, and [`resolveScrollPosition`](#resolvescrollpositionelement-position)'s `position`.
@@ -550,30 +588,35 @@ sticky.createOverlapScroll({
550
588
  }); // pin until the very bottom of the page
551
589
  ```
552
590
 
553
- `'max'` is only supported by [`createOverlapScroll`](#createoverlapscrolloptions) and [`resolveScrollPosition`](#resolvescrollpositionelement-position)/[`createResolvedTrigger`](#createresolvedtriggeroptions). `createStickyTrigger` and `createStickyPin` throw on it, because their own dwell padding or pin spacer adds to the document height `'max'` measures: the freeze window would depend on itself, growing the page a little more on every `refresh()`. GSAP defines `'max'` for `end`, not `start`. In raw GSAP 3.15.0, `start: 'max'` silently resolves to `0` rather than the scroller's max, so this module rejects it for `start` instead of reproducing that.
591
+ `'max'` is only supported by [`createOverlapScroll`](#createoverlapscrolloptions) and [`resolveScrollPosition`](#resolvescrollpositionelement-position)/[`createResolvedTrigger`](#createresolvedtriggeroptions). `createStickyTrigger` throws on it: a Scene layer's dwell padding is part of the document height `'max'` measures and as long as the freeze window, so lengthening the window moves `'max'` by the same amount and `'max'` can't settle the length. `createStickyPin` throws on it too. GSAP defines `'max'` for `end`, not `start`. In raw GSAP 3.15.0, `start: 'max'` silently resolves to `0` rather than the scroller's max, so this module rejects it for `start` instead of reproducing that.
554
592
 
555
593
  ## Constraints and caveats
556
594
 
557
595
  - The structure directly under the shared container changes because of the added wrapper elements. Direct-child selectors like `.container__inner > .scene`, `:nth-child()`, adjacent-sibling selectors (`+`/`~`), and flex/grid layout on the shared container itself may break across the wrapper boundary
596
+ - The same goes for selector strings, including those you pass to this module (`trigger`, `endTrigger`, `cover`, `element`, `scrollMarginTargets`). After `refresh()`, Scene layers wrap the shared container itself, `createOverlapScroll` wraps `trigger` and the siblings before it, and `createStickyPin` wraps `trigger`. A selector that steps from parent to child or between siblings across a wrapper then stops matching (`main > .container__inner`, `.container__inner > p:first-child`, `scrollMarginTargets: ':scope > section'`), and `'div'` or `'*'` matches the wrappers too. Class and id selectors, the default `'[id]'` included, match as before
558
597
  - `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
559
598
  - `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
560
599
  - That shared parent also caps how far `cover` can rise: it needs `end - start` worth of content below `trigger`, or the browser releases the wrapper mid-rise, at a point that shifts with the window size (see [Room for the rise](#room-for-the-rise))
561
600
  - Everything in that parent up to and including `trigger` is pinned with `trigger` until the rise runs out of room, and [`resolveScrollPosition`](#resolvescrollpositionelement-position), [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances) and same-page links don't account for that pin. A position such an element reaches before the pin starts resolves correctly. A later one is only reached after `cover` has risen over the element, so it has no uncovered scroll position: a same-page link lands while the element is pinned, below the viewport's top edge and possibly already under `cover`
562
601
  - `createStickyTrigger` and `createOverlapScroll` throw if `trigger` isn't inside the shared container. Both build their structure inside it, so a `trigger` elsewhere would wrap, move and style elements the instance doesn't own
563
602
  - `createStickyPin` works on either side of the container, and throws only for a `trigger` that encloses it (the container itself, or an ancestor). A pin makes `trigger` itself `position:sticky` inside a box holding the pin range, which would pin the container and the layers' dwell padding along with it
564
- - Selector strings for `trigger`/`endTrigger`/`cover`/`element` resolve against the whole document, as GSAP's own `trigger` does, rather than within the shared container; only the `trigger` rules above restrict where a match may land. Validate or scope these values yourself if they come from content you don't control
603
+ - Selector strings for `trigger`/`endTrigger`/`cover`/`element` resolve against the whole document, as GSAP's own `trigger` does, rather than within the shared container; only the `trigger` rules above restrict where a match may land
604
+ - Every option, including ScrollTrigger options passed through, is meant to come from the page's own code. If some come from a configuration other people can edit, build the options object from values you allow instead of passing the configuration through: selectors reach the whole document, callbacks and function-valued `start`/`end` run in the page, and `scrollMarginTargets` writes to every element it matches on each `refresh()`
565
605
  - ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
566
606
  - 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))
607
+ - A function-valued `start`/`end` of `createStickyTrigger`, `createOverlapScroll` or `createStickyPin` runs inside `refresh()` and may call `refresh()`, `ScrollTrigger.refresh()`, a ScrollTrigger's `kill()`, `destroy()` or a `create*` method. A `refresh()` of the same instance from there makes the outermost `refresh()` measure once more before it returns. A `ScrollTrigger.refresh()` from these functions may not measure the instance again: when the outermost `refresh()` runs outside a GSAP refresh, GSAP can miss a change the function makes until a `ScrollTrigger.refresh()` after the outermost `refresh()` returns, though the page itself ends up right. A function that registers a new layer and calls `refresh()` or `ScrollTrigger.refresh()` on every call never settles: the page hangs, and with `refresh()` it ends in a stack overflow. Prefer changing the layout outside these functions, then calling `ScrollTrigger.refresh()` (see [Calling refresh](#calling-refresh))
567
608
  - 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))
568
609
  - 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
569
- - `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
610
+ - `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` (see [End syntax](#end-syntax)). End a Scene layer on a dwell distance and a pin on a position clause against `endTrigger` instead, or use `createOverlapScroll`, which takes `'max'`
570
611
  - 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
612
  - 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))
572
- - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
613
+ - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls on one instance throws. Nothing checks this across instances, so give each element to one instance: `createStickyPin` on one element from two instances nests one instance's wrapper inside the other's, and once the outer one's pin (the one whose `refresh()` wrapped the element first) is killed, the inner one's range is wrong
573
614
  - 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))
574
615
  - 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
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))
616
+ - `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()`, and when the instance's last layer or pin is killed. Pass `scrollMarginTargets: null` to opt out (see [Same-page links](#same-page-links))
617
+ - A ScrollTrigger of your own that pins with GSAP (its `pin` option) outside the shared container leaves what this module measured stale when the pin's spacing changes in a GSAP refresh (a resize with an `end` in `%` of the viewport, say), because GSAP sizes its pins after the `refreshInit` in which this module measures: below the pin, a layer's window opens early or late by the change, and what reads the document's height, such as a cover's `'max'` end, misses the new height. One more `ScrollTrigger.refresh()` puts it right. To avoid the gap, pin that section with `createStickyTrigger` instead, as a layer of the instance it leaves stale, inside that instance's shared container. `createStickyPin` can't replace it, since, unlike GSAP's pin spacing, it adds no scroll distance
576
618
  - 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
619
+ - Use one instance with layers per shared container at a time. Each instance counts only its own Scene layers' dwell: with two on one container, layers lower on the page open early by the other instance's dwell above them, whichever was created first, and if the two instances' layers alternate down the page, all dwell is lost. A new instance in each `gsap.matchMedia()` setup is fine when every layer and pin goes to `ScrollTrigger.create()`, since the setup's revert kills the previous instance's layers and hands the container back (see [`destroy()`](#destroy))
577
620
 
578
621
  ## License
579
622
 
@@ -1,6 +1,6 @@
1
1
  /*!
2
2
  * @license
3
- * StickyScrollTrigger v0.12.0
3
+ * StickyScrollTrigger v0.14.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