sticky-scroll-trigger 0.12.0 → 0.13.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.13.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.
@@ -550,30 +581,33 @@ sticky.createOverlapScroll({
550
581
  }); // pin until the very bottom of the page
551
582
  ```
552
583
 
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.
584
+ `'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
585
 
555
586
  ## Constraints and caveats
556
587
 
557
588
  - 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
589
+ - 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
590
  - `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
559
591
  - `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
560
592
  - 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
593
  - 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
594
  - `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
595
  - `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
596
+ - 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
597
+ - 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
598
  - ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
566
599
  - 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))
567
600
  - 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
601
  - 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
602
+ - `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
603
  - 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
604
  - 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
605
  - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
573
606
  - 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
607
  - 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))
608
+ - `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))
576
609
  - 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
610
+ - 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
611
 
578
612
  ## License
579
613
 
@@ -1,6 +1,6 @@
1
1
  /*!
2
2
  * @license
3
- * StickyScrollTrigger v0.12.0
3
+ * StickyScrollTrigger v0.13.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