sticky-scroll-trigger 0.15.0 → 0.17.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.
|
|
43
|
+
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.17.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.
|
|
@@ -183,19 +183,19 @@ Inside GSAP's own refresh, a layer's `onRefreshInit` runs `refresh()` again only
|
|
|
183
183
|
|
|
184
184
|
Registers an overlap-scroll effect (`trigger` gets pinned while its siblings from `cover` onward scroll normally and rise up to cover it) and returns `ScrollTrigger.Vars`. No tween or dwell spacer is created. Since the return value only describes the freeze window, the effect works even without passing it to `ScrollTrigger.create()`, unless you need `markers` or callbacks.
|
|
185
185
|
|
|
186
|
-
| option | default
|
|
187
|
-
| ------------ |
|
|
188
|
-
| `trigger` | (required)
|
|
189
|
-
| `cover` | `trigger
|
|
190
|
-
| `start` | `'bottom bottom'`
|
|
191
|
-
| `end` | `null` (auto-computed)
|
|
192
|
-
| `endTrigger` | `trigger`
|
|
186
|
+
| option | default | description |
|
|
187
|
+
| ------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
188
|
+
| `trigger` | (required) | The element that gets pinned and covered. Must be inside the shared container; throws otherwise. Its own parent, which doesn't have to be the container itself, bounds how far the rise can run (see below) |
|
|
189
|
+
| `cover` | `trigger`'s next sibling | The first element of the covering side; this and all following siblings cover together. Must share the same parent as `trigger` (see [Constraints and caveats](#constraints-and-caveats)) |
|
|
190
|
+
| `start` | `'bottom bottom'` | Pinned position of `trigger`. See [position syntax](#position-syntax). Unlike `createStickyTrigger`'s `start`, this doesn't support an absolute scroll position (a bare number): it throws instead |
|
|
191
|
+
| `end` | `null` (auto-computed) | End of the freeze window. When `null`, computed automatically as "the distance until `cover`'s top edge reaches the top of the viewport" |
|
|
192
|
+
| `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax |
|
|
193
193
|
|
|
194
194
|
`start` and `end` are the two defaults this module doesn't take from GSAP, which pins at `'top top'` and ends at `'bottom top'`. The rise needs `cover` to begin off screen: pinned at the viewport's top, a `trigger` shorter than the viewport leaves the covering side already showing underneath it. `'bottom bottom'` rests `trigger` against the viewport's bottom edge instead, and the auto `end` measures the rise from there.
|
|
195
195
|
|
|
196
196
|
A `trigger` shorter than the viewport that also sits within a viewport height of the document top makes that default resolve to a negative freeze-window start, so part of the rise plays before scroll 0. The freeze window is not clamped here; see [Position syntax](#position-syntax) for why and how to avoid it.
|
|
197
197
|
|
|
198
|
-
`createOverlapScroll`
|
|
198
|
+
`createOverlapScroll` sets `position`/`z-index` on the covering side only where they compute to `static`/`auto`, so it never overrides other values, and restores its changes on GSAP `kill()`. The restore puts back the element's own inline value, `!important` included, and only while the property still holds the value the lift wrote, so a different value you set on the covering side afterwards (a `gsap.set()`, say) survives.
|
|
199
199
|
|
|
200
200
|
Every [`refresh()`](#refresh) runs that check again over the covering side as it stands: it raises an element added since, and hands back a property your own CSS has turned on in the meantime. Where the covering side holds a `createStickyPin` `trigger`, the pin's own wrapper rises in its place and the pinned element is left alone.
|
|
201
201
|
|
|
@@ -293,7 +293,23 @@ Clauses resolve exactly as they do elsewhere, including the one-token forms that
|
|
|
293
293
|
|
|
294
294
|
`endTrigger` and `end` both default to GSAP's own values. `'bottom top'` releases the pin once `endTrigger`'s bottom edge reaches the viewport's top edge, so naming an `endTrigger` and leaving `end` alone holds the pin for that element's own height past its top. Omit both and `trigger` pins against itself, held for its own height, the duration GSAP's `pin: true` gives.
|
|
295
295
|
|
|
296
|
-
`trigger` keeps its own space in the page: every [`refresh()`](#refresh) sizes its wrapper to `trigger`'s margin box, so registering a pin doesn't shorten the document or move what follows. The wrapping does change margin collapsing, though. `trigger`'s vertical margins stop at that wrapper instead of collapsing with its siblings', and no sizing can give that back, since the collapsing partner sits outside it. A `margin-bottom: 30px` above a `trigger` with `margin-top: 20px` occupies 30px unpinned and 50px pinned.
|
|
296
|
+
`trigger` keeps its own space in the page: every [`refresh()`](#refresh) sizes its wrapper to `trigger`'s margin box, so registering a pin doesn't shorten the document or move what follows. Where `trigger`'s height would resolve against the wrapper instead (a percentage `height`, `min-height` or `max-height`), every `refresh()` also reads it with the wrappers out of the layout and writes it on `trigger` in px (`min-height` and `max-height` too, at that height, all `!important` so a stylesheet's `!important` doesn't win over them), as GSAP holds a pin's height: the percentage resolves against `trigger`'s own container, and, like an item's box below, stays as last read until the next `refresh()`. A height set by the content, in px or in viewport units isn't written, so it goes on following them between refreshes. A pin inside another pin's `trigger` keeps the percentage height it had before either was pinned, so under an outer `trigger` with an auto height it stays auto, where GSAP's resolves against the height GSAP holds on the outer pin. The wrapping does change margin collapsing, though. `trigger`'s vertical margins stop at that wrapper instead of collapsing with its siblings', and no sizing can give that back, since the collapsing partner sits outside it. A `margin-bottom: 30px` above a `trigger` with `margin-top: 20px` occupies 30px unpinned and 50px pinned.
|
|
297
|
+
|
|
298
|
+
In a flex or grid container, floated, or inline-level (`inline-block`, say), the wrapper takes over `trigger`'s place, and `trigger` keeps its own box inside it, as with GSAP's pin-spacer: every `refresh()` reads the box the container gives `trigger`, holds it on the wrapper in px (a grid item's width is left to the grid), and writes `trigger`'s width, height, padding and margins in px, as GSAP writes a pin's (`max-width` at the width, `max-height` and `min-height` at the height), `!important` as above. A `clear` on `trigger` applies to the wrapper too, wherever it applied to `trigger`.
|
|
299
|
+
|
|
300
|
+
Those values stay as last read until the next `refresh()`, which a window resize runs on its own; a container resized any other way, or content or a class that changes `trigger`'s size, needs one, and so does a `trigger` that had no box when it last ran (inside a hidden tab, say), which until then sits by its own flex or grid properties alone. Each `refresh()` puts `trigger`'s own inline values for those properties back before it reads, and a kill or `destroy()` puts them back for good; a value set on one of them since the last `refresh()` (with `gsap.set`, say) is kept instead. A CSS `transition` on any of them plays on `trigger` each time a `refresh()` changes them, through sizes that are neither the old one nor the new. A CSS `@keyframes` animation of them, on the other hand, stops while `trigger` is pinned, since an `!important` inline value outranks it.
|
|
301
|
+
|
|
302
|
+
Two differences remain, since `trigger` is now a box inside the wrapper rather than the container's item. Its content's vertical margins can collapse through its top or bottom edge where it has no padding or border there, shifting `trigger`'s own box, background included, by that margin while the content stays put. And an `inline-block` `trigger` with `vertical-align: middle`, `text-top` or `bottom` sits lower, aligned in a line of the wrapper's own instead of the one around it; `baseline` and `top` line up as before, and what follows doesn't move. To avoid these, pin an element inside the item instead:
|
|
303
|
+
|
|
304
|
+
```html
|
|
305
|
+
<!-- the flex item, styled as before -->
|
|
306
|
+
<aside class="sidebar">
|
|
307
|
+
<!-- createStickyPin({ trigger: '.sidebar__pin' }) -->
|
|
308
|
+
<div class="sidebar__pin">…</div>
|
|
309
|
+
</aside>
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
The item keeps its place and size, background included, and only what's inside it is pinned, where GSAP's `pin: true` on the item moves the item's whole box.
|
|
297
313
|
|
|
298
314
|
Internally, the element wrapping `trigger` renders beyond its own section's bounds, into the visual area of following elements. Make sure the ancestor section containing `trigger` isn't hidden behind a later section in DOM order (e.g. via `position: relative; z-index: ...`).
|
|
299
315
|
|
|
@@ -398,7 +414,7 @@ Recomputes each layer's sticky `top`, dwell spacer height, and freeze window (`s
|
|
|
398
414
|
|
|
399
415
|
It measures at scroll 0, as GSAP's own refresh does, so a sticky element around what it measures, whether the page's own or another instance's, sits where GSAP sees it. Away from the top, a call of your own scrolls there and back before it returns, as `ScrollTrigger.refresh()` does. Nothing is painted in between, though a `scroll` event fires. While the page scrolls, it does so only with such a sticky element around what it measures, since the trip stops the scroll; without one it measures where the page is, with the same result. Inside GSAP's refresh it scrolls there and back too, ahead of GSAP's own trip.
|
|
400
416
|
|
|
401
|
-
Kill-driven updates are deferred to a microtask, or to a GSAP refresh later in the same task, and coalesced per task. While the page scrolls, they wait for the scroll to stop, as GSAP's own refresh does. Killing `createStickyTrigger` layers while another layer or pin is left leaves their nesting levels in the DOM, no longer sticky and with no dwell, so nothing inside the managed container moves for them; they come off at the next rebuild. Adding or reordering triggers rebuilds the nesting, and killing the last layer or pin takes it down
|
|
417
|
+
Kill-driven updates are deferred to a microtask, or to a GSAP refresh later in the same task, and coalesced per task. While the page scrolls, they wait for the scroll to stop, as GSAP's own refresh does. Killing `createStickyTrigger` layers while another layer or pin is left leaves their nesting levels in the DOM, no longer sticky and with no dwell, so nothing inside the managed container moves for them; they come off at the next rebuild. Adding or reordering triggers rebuilds the nesting, and killing the last layer or pin takes it down. In Chrome and Edge 133+ and Firefox 144+ that DOM move uses `moveBefore()`, which keeps `<iframe>` elements inside the managed container loaded and focused inputs focused (Chrome still restarts a running CSS animation, and Firefox resets the scroll position of an element scrolled inside). Safari has no `moveBefore()`, so there the move reloads iframes and drops focus. This cannot be disabled, so be careful when placing iframes or focus-sensitive inputs under the controller for Safari.
|
|
402
418
|
|
|
403
419
|
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' updates 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)).
|
|
404
420
|
|
|
@@ -425,7 +441,7 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
425
441
|
<a href="#chapter3">Chapter 3</a>
|
|
426
442
|
```
|
|
427
443
|
|
|
428
|
-
- Your own `scroll-margin-top` still applies. The correction is added to whatever value the element already computes to, never written over it, re-read on every `refresh()` (so a later change,
|
|
444
|
+
- Your own `scroll-margin-top` still applies. The correction is added to whatever value the element already computes to, never written over it, re-read on every `refresh()` (so a later change, a responsive breakpoint or an inline value set from JS, is picked up too), and `destroy()` puts the element's own inline value back, `!important` included
|
|
429
445
|
- A fixed header's offset is a different case, applying to every scroll rather than only those inside the shared container. CSSOM View says `scroll-padding-top` (on the scroller) and `scroll-margin-top` (on the target) add together, so in principle the header offset could live there, independently of this module's correction. In practice, don't: Firefox drops `scroll-padding-top` from a fragment jump once any `position:sticky` element on the page has engaged, landing short by exactly the header height (see ARCHITECTURE.md's "Firefox drops scroll-padding-top" for how this was verified). Fold it into `--sst-scroll-margin-top-offset` instead (below), as the repository's demo does in `style.css`'s `html` rule
|
|
430
446
|
- To land deliberately short of or past a target, set the `--sst-scroll-margin-top-offset` custom property (a length) on it, or on any ancestor to cover several targets at once (it inherits like any other custom property). A positive value lands short, settling below the viewport's top edge instead of flush with it; negative overshoots. Being a plain `var()`, the browser reads it live at scroll-into-view time, so unlike the author-`scroll-margin-top` case above, no `refresh()` call is needed for a change to take effect, including when it changes which scenes' dwell the target waits out
|
|
431
447
|
|
|
@@ -445,7 +461,7 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
445
461
|
|
|
446
462
|
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.
|
|
447
463
|
|
|
448
|
-
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 the Scene/Cover wrappers the library adds are switched, and they carry an inline `transition: none !important`, so a page-wide `transition` rule doesn't animate the switch. A `createStickyPin` trigger stays sticky, as does any sticky element of your own. While the switch is on for an instance with a Scene/Cover layer, the pin triggers of every instance that can use it (`'always'`, or `'auto'` on WebKit, deep or not), and every other sticky element around the library's elements (yours, or a pin of an instance that can't), are set to `static` for a moment at each `refresh()` to measure the layout, then get back what they had: such a pin trigger the `position` the pin gave it, any other element its `
|
|
464
|
+
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 the Scene/Cover wrappers the library adds are switched, and they carry an inline `transition: none !important`, so a page-wide `transition` rule doesn't animate the switch. A `createStickyPin` trigger stays sticky, as does any sticky element of your own. While the switch is on for an instance with a Scene/Cover layer, the pin triggers of every instance that can use it (`'always'`, or `'auto'` on WebKit, deep or not), and every other sticky element around the library's elements (yours, or a pin of an instance that can't), are set to `static` for a moment at each `refresh()` to measure the layout, then get back what they had: such a pin trigger the `position` the pin gave it, any other element its own inline `position`, `!important` included, in a way a strict Content Security Policy allows. A `MutationObserver` on one sees those two writes. Everything is left alone when the shared container sits inside a scroll container or `body` scrolls the page instead of the window.
|
|
449
465
|
|
|
450
466
|
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.
|
|
451
467
|
|
|
@@ -600,7 +616,7 @@ sticky.createOverlapScroll({
|
|
|
600
616
|
- 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
|
|
601
617
|
- 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
|
|
602
618
|
- `position:sticky` doesn't work if any ancestor of the pinned target has `overflow` set to `hidden`, `auto` or `scroll` on either axis. `clip` keeps it working. So does any value on `html`, and on `body` while `html`'s is `visible`, since the browser then applies it to the viewport
|
|
603
|
-
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
|
|
619
|
+
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent. They're read in the page's own markup, through the wrappers of pins, Scene layers and the instance's own overlaps (not another instance's overlaps), so an overlap gets the same `cover` and wrapper whether it registers before or after those are built
|
|
604
620
|
- 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))
|
|
605
621
|
- 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`
|
|
606
622
|
- `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
|
|
@@ -618,10 +634,10 @@ sticky.createOverlapScroll({
|
|
|
618
634
|
- 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
|
|
619
635
|
- 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))
|
|
620
636
|
- 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
|
|
621
|
-
- `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))
|
|
637
|
+
- `refresh()` writes an inline `scroll-margin-top: ... !important` 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))
|
|
622
638
|
- 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
|
|
623
639
|
- A `resolveScrollPosition` or `getScrollTop` call made while the page scrolls (while `ScrollTrigger.isScrolling()` says so, which lasts a moment past the scroll's end, or from a ScrollTrigger callback the scroll runs) measures an element inside another instance's pin, or inside a `position: sticky` element of the page's own, where it sits at that moment, since going to scroll 0 would stop the scroll. When that element is stuck, the result comes out late by however far it is stuck. Call it at rest, or from a function-valued `start`/`end`, which runs inside a refresh
|
|
624
|
-
- 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. 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
|
|
640
|
+
- 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. For a target inside both, [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances)'s ownership check also picks whichever instance is listed first, and a same-page link to such a target lands by one instance's correction only. Give each instance its own part of the page instead
|
|
625
641
|
- 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))
|
|
626
642
|
|
|
627
643
|
## License
|