sticky-scroll-trigger 0.9.0 → 0.11.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
|
@@ -13,6 +13,10 @@ The only dependency is GSAP's ScrollTrigger types.
|
|
|
13
13
|
|
|
14
14
|
See the repository's `demo/index.html` + `demo/src/main.ts` for a live example, and `ARCHITECTURE.md` for why nested sticky was chosen over `pin`, and how it works internally.
|
|
15
15
|
|
|
16
|
+
## Demo
|
|
17
|
+
|
|
18
|
+
The [CodePen demo](https://codepen.io/editor/kuninori-ogino/pen/01a083a9-37ab-79e1-a955-cc97d7957f45) shows each effect running.
|
|
19
|
+
|
|
16
20
|
## Requirements
|
|
17
21
|
|
|
18
22
|
| requirement | description |
|
|
@@ -36,7 +40,7 @@ npm install gsap sticky-scroll-trigger
|
|
|
36
40
|
For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
|
|
37
41
|
|
|
38
42
|
```html
|
|
39
|
-
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.
|
|
43
|
+
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.11.0/dist/StickyScrollTrigger.global.min.js"></script>
|
|
40
44
|
```
|
|
41
45
|
|
|
42
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.
|
|
@@ -159,14 +163,16 @@ Registers a layer that pins a scene and advances its effect, and returns `Scroll
|
|
|
159
163
|
| `pin` / `pinSpacing` / `anticipatePin` / `pinnedContainer` / `pinReparent` / `pinSpacer` / `pinType` | Pinning is handled by `position:sticky`, not GSAP pinning, so these have no effect |
|
|
160
164
|
| `horizontal` / `scroller` / `containerAnimation` | This module assumes vertical, window-based scrolling; setting these shifts positions |
|
|
161
165
|
|
|
166
|
+
Nested Scene layers are accounted for automatically, so `pinnedContainer` isn't needed (see [End syntax](#end-syntax)).
|
|
167
|
+
|
|
162
168
|
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.
|
|
163
169
|
|
|
164
|
-
| option | default | description
|
|
165
|
-
| ------------ | -------------- |
|
|
166
|
-
| `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise
|
|
167
|
-
| `start` | `'top top'` | Where the scene lands in the viewport while pinned (same idea as sticky's CSS `top`). Same default GSAP itself uses for a pinned trigger. See [position syntax](#position-syntax)
|
|
168
|
-
| `end` | `'bottom top'` | End of the freeze window. Auto-detects between a dwell distance and a position clause (see [end syntax](#end-syntax)). Same default GSAP uses too: dwell for the trigger's own height, not a fixed distance |
|
|
169
|
-
| `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax. Must be inside the shared container (see below)
|
|
170
|
+
| option | default | description |
|
|
171
|
+
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
172
|
+
| `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container; throws otherwise |
|
|
173
|
+
| `start` | `'top top'` | Where the scene lands in the viewport while pinned (same idea as sticky's CSS `top`). Same default GSAP itself uses for a pinned trigger. See [position syntax](#position-syntax) |
|
|
174
|
+
| `end` | `'bottom top'` | End of the freeze window. Auto-detects between a dwell distance and a position clause (see [end syntax](#end-syntax)). Same default GSAP uses too: dwell for the trigger's own height plus the dwell of the scenes nested inside it, not a fixed distance |
|
|
175
|
+
| `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax. Must be inside the shared container (see below) |
|
|
170
176
|
|
|
171
177
|
### `createOverlapScroll(options)`
|
|
172
178
|
|
|
@@ -182,6 +188,8 @@ Registers an overlap-scroll effect (`trigger` gets pinned while its siblings fro
|
|
|
182
188
|
|
|
183
189
|
`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.
|
|
184
190
|
|
|
191
|
+
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.
|
|
192
|
+
|
|
185
193
|
`createOverlapScroll` adjusts `position`/`z-index` on the covering side only when needed, never overrides explicit values, and restores its changes on GSAP `kill()`. The restore clears a property only while it still holds the value the lift wrote, so a different value you set on the covering side afterwards (a `gsap.set()`, say) survives.
|
|
186
194
|
|
|
187
195
|
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.
|
|
@@ -191,10 +199,10 @@ Every [`refresh()`](#refresh) runs that check again over the covering side as it
|
|
|
191
199
|
Pinning here is plain `position:sticky`, and the browser keeps a sticky element stuck only until its containing block's bottom edge catches up with it. That containing block is `trigger`'s own parent, not the shared container:
|
|
192
200
|
|
|
193
201
|
```
|
|
194
|
-
trigger's parent's bottom edge - trigger's bottom edge >= end - start
|
|
202
|
+
trigger's parent's bottom edge - trigger's bottom edge >= end - start - dwell
|
|
195
203
|
```
|
|
196
204
|
|
|
197
|
-
With the auto `end`,
|
|
205
|
+
`dwell` is that of any Scene layer freezing mid-rise: it holds the whole container, `cover` and the parent included, so it uses no room. With the auto `end`, `end - start - dwell` is where `cover`'s top edge sits when the freeze starts: `start`'s pinned offset, plus `trigger`'s own height, plus any gap between the two. Under the defaults (`start: 'bottom bottom'`, `cover` directly after `trigger`) it comes to one viewport height; a `trigger` taller than the viewport, pinned near the top, needs more.
|
|
198
206
|
|
|
199
207
|
With less room than that, the browser releases the wrapper mid-rise: `trigger` scrolls away before `cover` has covered it, at a point that moves with the window size, since the requirement scales with the viewport while the room doesn't. Content after `trigger`'s parent never counts, however long the page is. Add the missing height below `trigger` (a taller `cover`, or a spacer after it), or keep the sections that follow inside the same parent rather than wrapping `trigger` and `cover` in a box of their own.
|
|
200
208
|
|
|
@@ -234,7 +242,7 @@ ScrollTrigger.create(
|
|
|
234
242
|
);
|
|
235
243
|
```
|
|
236
244
|
|
|
237
|
-
The rise picks up where the scrub ends, with no arithmetic on your side, because `refresh()` adds a Scene layer's dwell to
|
|
245
|
+
The rise picks up where the scrub ends, with no arithmetic on your side, because `refresh()` adds a Scene layer's dwell to a cover layer's freeze window whenever the scene freezes first, including one that freezes just as the rise would begin.
|
|
238
246
|
|
|
239
247
|
The marker sits on the scene's bottom edge, so one `'bottom bottom'` describes both layers and nothing moves at the handover. The scene pins with that edge on the viewport's bottom, and `cover`, which begins there, stays just off screen for the whole hold. Pin the scene anywhere else and you have to reconcile the two clauses by hand, since a zero-height marker resolves any clause to a plain viewport position. Its `start` has to name wherever the scene's bottom edge sits while pinned, or `trigger` jumps.
|
|
240
248
|
|
|
@@ -274,7 +282,7 @@ sticky.refresh();
|
|
|
274
282
|
|
|
275
283
|
Here `start` means only where the element sits while pinned, not when pinning begins, as it does for the other methods. Pinning begins the moment `trigger` reaches that position naturally, which is CSS's decision rather than a separate number to set, so a pin's position and the scroll position it engages at are one setting.
|
|
276
284
|
|
|
277
|
-
That's why `start` throws on an [absolute scroll position](#absolute-scroll-position) (`start: 20`, which GSAP reads as scroll position 20) instead of silently treating it as a px distance. `top` is its own option for the same reason: with the bare-number slot reserved for GSAP's meaning, `'top 20px'` would otherwise be a pin's only way to say "20px below the top of the viewport". `end` does take an absolute scroll position (`end: 3000` releases at scroll 3000), since a release point is a real thing to ask for on the scroll axis.
|
|
285
|
+
That's why `start` throws on an [absolute scroll position](#absolute-scroll-position) (`start: 20`, which GSAP reads as scroll position 20) instead of silently treating it as a px distance. `top` is its own option for the same reason: with the bare-number slot reserved for GSAP's meaning, `'top 20px'` would otherwise be a pin's only way to say "20px below the top of the viewport". `end` does take an absolute scroll position (`end: 3000` releases at scroll 3000), since a release point is a real thing to ask for on the scroll axis. If scroll 3000 falls inside a Scene layer's freeze, a pin inside the shared container holds until that freeze ends. Pinning also starts only after the dwell of every scene that freezes first, so the pin can hold for less scroll than GSAP's, or not at all, as with a Scene layer's [absolute `end`](#absolute-scroll-position).
|
|
278
286
|
|
|
279
287
|
Clauses resolve exactly as they do elsewhere, including the one-token forms that name the element's own side: `'top 20px'` puts the element's top 20px below the viewport's top edge, while `'20px'` puts it 20px above.
|
|
280
288
|
|
|
@@ -284,7 +292,7 @@ Clauses resolve exactly as they do elsewhere, including the one-token forms that
|
|
|
284
292
|
|
|
285
293
|
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: ...`).
|
|
286
294
|
|
|
287
|
-
See the repository's `ARCHITECTURE.md` ("
|
|
295
|
+
See the repository's `ARCHITECTURE.md` ("How `createStickyPin` accounts for nested-sticky lag") for how a pin's release allows for the dwell of Scene layers between `trigger` and `endTrigger`, and why `trigger` needs two nested wrapper divs.
|
|
288
296
|
|
|
289
297
|
### `createResolvedTrigger(options)`
|
|
290
298
|
|
|
@@ -304,12 +312,12 @@ gsap.to(plainBox, {
|
|
|
304
312
|
});
|
|
305
313
|
```
|
|
306
314
|
|
|
307
|
-
| option | default | description
|
|
308
|
-
| ------------ | -------------- |
|
|
309
|
-
| `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger`
|
|
310
|
-
| `start` | `'top bottom'` | [Position syntax](#position-syntax), resolved relative to `trigger`
|
|
311
|
-
| `end` | `'bottom top'` | [Position syntax](#position-syntax), resolved relative to `endTrigger`
|
|
312
|
-
| `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split)
|
|
315
|
+
| option | default | description |
|
|
316
|
+
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
317
|
+
| `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger` |
|
|
318
|
+
| `start` | `'top bottom'` | [Position syntax](#position-syntax), resolved relative to `trigger` |
|
|
319
|
+
| `end` | `'bottom top'` | [Position syntax](#position-syntax), resolved relative to `endTrigger` |
|
|
320
|
+
| `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split). May sit outside the shared container |
|
|
313
321
|
|
|
314
322
|
Omit `start` and `end` and the range runs from `trigger`'s top edge entering the viewport at the bottom to `endTrigger`'s bottom edge leaving it at the top, GSAP's own defaults for a trigger that doesn't pin.
|
|
315
323
|
|
|
@@ -319,7 +327,7 @@ If you need different reference elements or custom progress logic, use `resolveS
|
|
|
319
327
|
|
|
320
328
|
### `resolveScrollPosition(element, position)`
|
|
321
329
|
|
|
322
|
-
For any element inside the shared container (registered or not), returns the absolute scroll position (px) for GSAP position syntax (`element` + `position`). As with `trigger`/`endTrigger`/`cover` above, `element` also accepts a CSS selector string in addition to an `HTMLElement`. Use this to keep plain ScrollTriggers inside nested sticky in sync with real scroll distance. If `start` and `end` use the same element, [`createResolvedTrigger`](#createresolvedtriggeroptions) is usually simpler.
|
|
330
|
+
For any element inside the shared container (registered or not), returns the absolute scroll position (px) for GSAP position syntax (`element` + `position`). As with `trigger`/`endTrigger`/`cover` above, `element` also accepts a CSS selector string in addition to an `HTMLElement`. Use this to keep plain ScrollTriggers inside nested sticky in sync with real scroll distance. An element outside the container gets no dwell added, since the scenes don't hold it back. If `start` and `end` use the same element, [`createResolvedTrigger`](#createresolvedtriggeroptions) is usually simpler.
|
|
323
331
|
|
|
324
332
|
```ts
|
|
325
333
|
const sticky = new StickyScrollTrigger(".container__inner");
|
|
@@ -393,7 +401,7 @@ It only cleans up DOM/styles managed by this module. You still need to kill acti
|
|
|
393
401
|
|
|
394
402
|
## Same-page links
|
|
395
403
|
|
|
396
|
-
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 every
|
|
404
|
+
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.
|
|
397
405
|
|
|
398
406
|
`refresh()` declares that difference to the browser by keeping `scroll-margin-top` in sync on every element inside the shared container that matches `scrollMarginTargets` (`'[id]'` by default). Nothing else is needed: plain `<a href="#target">` links, `scrollIntoView()`, `:target` and a `#hash` on load all land correctly as written.
|
|
399
407
|
|
|
@@ -404,7 +412,7 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
404
412
|
|
|
405
413
|
- 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, e.g. a responsive breakpoint, is picked up too), and `destroy()` puts the original inline value back
|
|
406
414
|
- 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
|
|
407
|
-
- 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
|
|
415
|
+
- 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
|
|
408
416
|
|
|
409
417
|
```css
|
|
410
418
|
/* A fixed header's height, folded in here rather than into scroll-padding-top (see above). */
|
|
@@ -442,7 +450,7 @@ A token carrying `%` on both the base and the offset (`'50%+=10%'`) is one delib
|
|
|
442
450
|
|
|
443
451
|
A trailing `px` (`top 100px`, `center+=50px`) is accepted and ignored, the same idea as GSAP's own `_offsetToPx`, which only special-cases `%` and otherwise passes the value through `parseFloat`. This module isn't as lenient as GSAP toward other unrecognized suffixes, though: an actually-unsupported unit like `top 100vh` still throws, rather than silently behaving like `top 100`.
|
|
444
452
|
|
|
445
|
-
The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start: 'clamp(top center)'`, which holds the resolved position inside the scroller's own range) is not part of it and throws. Nothing clamps the freeze window either, so a clause that resolves past the top of the document keeps its negative value: a Scene layer sitting at the very start of the container with `start: 'top bottom'` begins one viewport height before scroll 0. `end` is the exception, already clamped to `start`.
|
|
453
|
+
The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start: 'clamp(top center)'`, which holds the resolved position inside the scroller's own range) is not part of it and throws. Nothing clamps the freeze window either, so a clause that resolves past the top of the document keeps its negative value: a Scene layer sitting at the very start of the container with `start: 'top bottom'` begins one viewport height before scroll 0, its wrapper torn that far down the flow and its dwell cut to match, so a scrubbed tween is already part-done at load. [`createOverlapScroll`](#createoverlapscrolloptions)'s `'bottom bottom'` default reaches this with no `start` passed when the covered `trigger` sits within a viewport height of the document top and is shorter than the viewport (`freezeStart` is `triggerTop - (viewportHeight - triggerHeight)`), so part of the rise is already showing at scroll 0. To avoid it, give `trigger` at least a viewport's height, or move it further down the page. There is no opt-out here: `clamp()` is rejected, and a cover layer's sticky offset does not reference the freeze window's start, so clamping the window would not move it. `end` is the exception, already clamped to `start`.
|
|
446
454
|
|
|
447
455
|
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.
|
|
448
456
|
|
|
@@ -452,6 +460,10 @@ GSAP treats a value as an absolute scroll position rather than a clause whenever
|
|
|
452
460
|
|
|
453
461
|
`start: '500'` (or `start: 500`) freezes starting at absolute scroll position 500px, ignoring the trigger's natural position and any preceding dwell. `end: '500'` ends the freeze window at 500px the same way, clamped to `start` if that would put `end` before it, matching GSAP's own `end = Math.max(start, ...)`.
|
|
454
462
|
|
|
463
|
+
When an absolute `start` falls inside another Scene layer's freeze window, the reported window (what GSAP gets, and so `self.start`/`self.end` and callbacks) keeps the written `start` and its length, as GSAP's own pins overlap. The page itself can't freeze twice at once, so it freezes only for the part of that window the other scene hasn't already frozen; positions (`resolveScrollPosition`, same-page links, cover layers and pins) follow the page.
|
|
464
|
+
|
|
465
|
+
An absolute `end` can give a Scene layer's window a different length than GSAP's pin. A position-clause `start` waits out the dwell of every scene that freezes first, including one enclosing `trigger`, one inside it, or one later in the DOM, while GSAP's pin starts after the spacers already placed above it. The wait doesn't change the length of a dwell or position-clause `end`, which is measured from that start, but an absolute one stays at the written value, so the window is shorter by however much later it starts than GSAP's, down to zero once the start passes the end. GSAP's `pinnedContainer` also delays the start for an enclosing scene, but moves an absolute `end` along with it. A scene above `trigger` that freezes later doesn't delay the start, which can make the window longer, as GSAP's pins created in another order would give. An absolute `start` doesn't wait, so with an absolute `end` the window keeps the written length.
|
|
466
|
+
|
|
455
467
|
`'500 top'` (two tokens) and `'500px'` (a suffix) don't qualify; they resolve as offsets via the bare-number row in the table above, same as GSAP.
|
|
456
468
|
|
|
457
469
|
> [`createOverlapScroll`](#createoverlapscrolloptions)'s `start` doesn't support absolute scroll positions: a cover layer's sticky position is always computed relative to its own wrapper (see the repository's `ARCHITECTURE.md`), which has no equivalent for one. It throws instead; use a position clause.
|
|
@@ -487,9 +499,19 @@ A `'+='` value with a space in it (`'+=100 bottom'`) is a position clause too, a
|
|
|
487
499
|
|
|
488
500
|
One pair can't compose: a `start` whose element token already carries an offset (`'top+=50 bottom'`) throws. GSAP splits a token at its first `=`, so it would keep the `50` and silently discard the `end`'s own offset. A signed number (`'-50 top'`) composes normally, matching GSAP.
|
|
489
501
|
|
|
490
|
-
If `endTrigger` points to another registered layer
|
|
502
|
+
If `endTrigger` points to another registered layer's `trigger`, it's resolved like any other element, by the rules in the next paragraph, and that layer's own `trigger` counts as enclosing it. A forward reference (pointing to a layer later in DOM order) only works from `createOverlapScroll`'s cover layer; a `createStickyTrigger` Scene layer throws instead.
|
|
503
|
+
|
|
504
|
+
For any `endTrigger` inside the container, registered or not, its raw DOM position is measured directly, then adjusted the way GSAP's own pins would move the point on it that `end` names, by the dwell of other registered Scene layers, including ones registered after this call. A scene whose `trigger` ends above `endTrigger` counts in full. One whose `trigger` sits inside `endTrigger` in the DOM grows it rather than moving it, so it counts by the share of `endTrigger`'s height in `end`'s element side: all of it for `'bottom top'`, half for `'center top'`, none for `'top+=100 top'`. A scene that encloses `endTrigger` counts in full if it freezes before that point reaches its viewport anchor. No other scene counts, even one that freezes first. The point `start` names on `trigger`, which the window's length is measured from, moves by the same rule.
|
|
505
|
+
|
|
506
|
+
An `end` on `trigger` itself counts the scenes nested inside `trigger` by the difference between `end`'s share and `start`'s, so the default `'bottom top'` after `'top top'` takes in their whole dwell. An absolute `start` has no share, and its `end` also counts every scene whose `trigger` ends above `trigger`.
|
|
507
|
+
|
|
508
|
+
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
|
+
|
|
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.
|
|
511
|
+
|
|
512
|
+
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.
|
|
491
513
|
|
|
492
|
-
|
|
514
|
+
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.
|
|
493
515
|
|
|
494
516
|
> 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.
|
|
495
517
|
>
|
|
@@ -515,14 +537,15 @@ sticky.createOverlapScroll({
|
|
|
515
537
|
- `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
|
|
516
538
|
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
|
|
517
539
|
- 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
|
+
- 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`
|
|
518
541
|
- `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
|
|
519
542
|
- `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
|
|
520
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. Validate or scope these values yourself if they come from content you don't control
|
|
521
544
|
- ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
|
|
522
545
|
- 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))
|
|
523
|
-
- A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can
|
|
546
|
+
- 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))
|
|
524
547
|
- 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
|
|
525
|
-
- If
|
|
548
|
+
- 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
|
|
526
549
|
- `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
|
|
527
550
|
- Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
|
|
528
551
|
- 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))
|