sticky-scroll-trigger 0.11.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 +67 -11
- package/dist/StickyScrollTrigger.d.ts +4 -1
- package/dist/StickyScrollTrigger.global.js +876 -143
- package/dist/StickyScrollTrigger.global.min.js +2 -2
- package/dist/StickyScrollTrigger.js +876 -143
- 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.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.
|
|
@@ -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,8 +166,12 @@ 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
|
|
|
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
|
+
|
|
170
175
|
| option | default | description |
|
|
171
176
|
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
172
177
|
| `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise |
|
|
@@ -389,16 +394,22 @@ An `element` outside every given instance's shared container is measured directl
|
|
|
389
394
|
|
|
390
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.
|
|
391
396
|
|
|
392
|
-
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)).
|
|
393
400
|
|
|
394
401
|
If surviving layers' freeze windows change after kill, GSAP's cached `start`/`end` values are synced internally.
|
|
395
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
|
+
|
|
396
405
|
### `destroy()`
|
|
397
406
|
|
|
398
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()`.
|
|
399
408
|
|
|
400
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.
|
|
401
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
|
+
|
|
402
413
|
## Same-page links
|
|
403
414
|
|
|
404
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.
|
|
@@ -426,6 +437,45 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
426
437
|
- 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
438
|
- 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
439
|
|
|
440
|
+
## Nested sticky performance
|
|
441
|
+
|
|
442
|
+
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.
|
|
443
|
+
|
|
444
|
+
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.
|
|
445
|
+
|
|
446
|
+
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.
|
|
447
|
+
|
|
448
|
+
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.
|
|
449
|
+
|
|
450
|
+
- 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
|
|
451
|
+
- 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
|
|
452
|
+
- 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
|
|
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
|
|
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'`
|
|
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
|
+
|
|
429
479
|
## Position syntax
|
|
430
480
|
|
|
431
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.
|
|
@@ -507,10 +557,12 @@ An `end` on `trigger` itself counts the scenes nested inside `trigger` by the di
|
|
|
507
557
|
|
|
508
558
|
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
559
|
|
|
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.
|
|
560
|
+
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
561
|
|
|
512
562
|
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
563
|
|
|
564
|
+
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.
|
|
565
|
+
|
|
514
566
|
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
567
|
|
|
516
568
|
> 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.
|
|
@@ -529,29 +581,33 @@ sticky.createOverlapScroll({
|
|
|
529
581
|
}); // pin until the very bottom of the page
|
|
530
582
|
```
|
|
531
583
|
|
|
532
|
-
`'max'` is only supported by [`createOverlapScroll`](#createoverlapscrolloptions) and [`resolveScrollPosition`](#resolvescrollpositionelement-position)/[`createResolvedTrigger`](#createresolvedtriggeroptions). `createStickyTrigger`
|
|
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.
|
|
533
585
|
|
|
534
586
|
## Constraints and caveats
|
|
535
587
|
|
|
536
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
|
|
537
590
|
- `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
|
|
538
591
|
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
|
|
539
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))
|
|
540
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`
|
|
541
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
|
|
542
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
|
|
543
|
-
- 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
|
|
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()`
|
|
544
598
|
- ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
|
|
545
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))
|
|
546
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))
|
|
547
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
|
|
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'`
|
|
548
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
|
|
549
|
-
-
|
|
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))
|
|
550
605
|
- Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
|
|
551
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))
|
|
552
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
|
|
553
|
-
- `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()
|
|
554
|
-
- Don't nest one `StickyScrollTrigger` instance's shared container inside another's
|
|
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))
|
|
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))
|
|
555
611
|
|
|
556
612
|
## License
|
|
557
613
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/*!
|
|
2
2
|
* @license
|
|
3
|
-
* StickyScrollTrigger v0.
|
|
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
|
|
@@ -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 { }
|