sticky-scroll-trigger 0.8.0 → 0.10.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/dist/StickyScrollTrigger.global.min.js"></script>
|
|
43
|
+
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.10.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
|
|
|
@@ -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). */
|
|
@@ -425,7 +433,7 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
425
433
|
| token | example | meaning |
|
|
426
434
|
| ----------- | --------------------------- | ------------------------------------------------------------- |
|
|
427
435
|
| keyword | `top` / `center` / `bottom` | 0% / 50% / 100% |
|
|
428
|
-
| bare number | `80` / `80px`
|
|
436
|
+
| bare number | `80` / `80px` / `-50` | ± px from the reference point (matches GSAP: only `%` scales) |
|
|
429
437
|
| percentage | `80%` | 80% of the target's height |
|
|
430
438
|
| px offset | `center+=50` / `top-=20` | ± px from the reference point |
|
|
431
439
|
| % offset | `top+=10%` | ± (relative to the target's height) |
|
|
@@ -436,17 +444,19 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
436
444
|
start: () => `center center+=${getHeaderHeight() / 2}`,
|
|
437
445
|
```
|
|
438
446
|
|
|
439
|
-
A px/% offset needs the `=` when it follows a keyword or number (`top+=50`, `80-=10%`), because GSAP uses the `=` itself to split the base from the offset. `top+50` isn't recognized syntax: GSAP silently resolves it to 0, treating the whole string as unparseable, while this module throws instead. Without a base, the `=` is optional (`+=500` and `+500` are equivalent), since there's nothing to split it from.
|
|
447
|
+
A px/% offset needs the `=` when it follows a keyword or number (`top+=50`, `80-=10%`), because GSAP uses the `=` itself to split the base from the offset. `top+50` isn't recognized syntax: GSAP silently resolves it to 0, treating the whole string as unparseable, while this module throws instead. Without a base, the `=` is optional (`+=500` and `+500` are equivalent), since there's nothing to split it from. A signed number is a base like any other and can carry an offset of its own: `-50+=100` is 50px from the reference point, because GSAP splits at the `=` and reads everything before it with `parseFloat`.
|
|
448
|
+
|
|
449
|
+
A token carrying `%` on both the base and the offset (`'50%+=10%'`) is one deliberate divergence. GSAP scales the offset only when the token's first `%` sits after the `=`, so a `%` base hides the offset's own and leaves it a plain px value: against a 400px element, GSAP reads `'50%+=10%'` as 210 where this module reads 240. Both units are honored here rather than reproducing that.
|
|
440
450
|
|
|
441
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`.
|
|
442
452
|
|
|
443
|
-
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`.
|
|
444
454
|
|
|
445
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.
|
|
446
456
|
|
|
447
457
|
### Absolute scroll position
|
|
448
458
|
|
|
449
|
-
|
|
459
|
+
GSAP treats a value as an absolute scroll position rather than a clause whenever it's just a number: a plain JS number, or a string `Number()` converts on its own with no keyword, second token, or `%`/`px` suffix, `'-50'` and `'1e3'` included. It ignores the reference element entirely in that case (`ScrollTrigger.js`'s `_parsePosition`: `isNaN(value) || (value = +value)`). This module follows the same rule for `start` and `end`, and for [`createStickyPin`](#createstickypinoptions)'s `end`, [`createResolvedTrigger`](#createresolvedtriggeroptions)'s `start`/`end`, and [`resolveScrollPosition`](#resolvescrollpositionelement-position)'s `position`.
|
|
450
460
|
|
|
451
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, ...)`.
|
|
452
462
|
|
|
@@ -462,7 +472,7 @@ If the entire value is just a number (a plain JS number, or a string that's noth
|
|
|
462
472
|
|
|
463
473
|
A bare number (or numeric string with no sign/`%`/`px`) is an absolute scroll position; see [Absolute scroll position](#absolute-scroll-position) above. `end` follows the same rule `start` uses, matching GSAP.
|
|
464
474
|
|
|
465
|
-
"Dwell distance": how many px to keep pinning after the freeze starts. Matching GSAP, only a string starting with the literal `'+='` prefix counts (or a `%`-suffixed `'+=...'`, resolved against the viewport height). A leading `-=`/`+`/`-` without `=`, or a `%` without `+=`, is a position clause instead (see below). A dwell `end` never consults `endTrigger`, again matching GSAP: the distance runs from wherever the freeze starts.
|
|
475
|
+
"Dwell distance": how many px to keep pinning after the freeze starts. Matching GSAP, only a string starting with the literal `'+='` prefix and holding no space counts (or a `%`-suffixed `'+=...'`, resolved against the viewport height). A leading `-=`/`+`/`-` without `=`, or a `%` without `+=`, is a position clause instead (see below), as is a `'+='` value with a space in it. A dwell `end` never consults `endTrigger`, again matching GSAP: the distance runs from wherever the freeze starts, or from the resolved `start` in [`createResolvedTrigger`](#createresolvedtriggeroptions), which has no freeze window.
|
|
466
476
|
|
|
467
477
|
| example | meaning |
|
|
468
478
|
| -------------------------------- | ------------------------------------- |
|
|
@@ -481,9 +491,23 @@ sticky.createStickyTrigger({
|
|
|
481
491
|
});
|
|
482
492
|
```
|
|
483
493
|
|
|
484
|
-
|
|
494
|
+
A `'+='` value with a space in it (`'+=100 bottom'`) is a position clause too, and GSAP gives it a base before resolving it: the element token from `start`. So `start: 'bottom bottom'` with `end: '+=100 bottom'` reads as `'bottom+=100 bottom'`, 100px past `endTrigger`'s own bottom edge. A `'top'` or `'0'` element token contributes nothing, which covers the `start` defaults of [`createStickyTrigger`](#createstickytriggeroptions) (`'0 0'`), [`createStickyPin`](#createstickypinoptions) (`'top top'`) and [`createResolvedTrigger`](#createresolvedtriggeroptions) (`'top bottom'`). [`createOverlapScroll`](#createoverlapscrolloptions) is the exception: its `'bottom bottom'` default puts a full `endTrigger` height into this `end` form even when the caller never passes `start`. Every method that takes a `start` and an `end` does this prefixing itself, since it resolves both sides into numbers before GSAP ever sees them.
|
|
495
|
+
|
|
496
|
+
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.
|
|
497
|
+
|
|
498
|
+
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.
|
|
499
|
+
|
|
500
|
+
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.
|
|
501
|
+
|
|
502
|
+
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`.
|
|
503
|
+
|
|
504
|
+
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.
|
|
505
|
+
|
|
506
|
+
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.
|
|
507
|
+
|
|
508
|
+
Some sets of Scene layers have no layout where every `end` agrees with what it counts, such as two nested scenes whose `endTrigger`s each lie past the other's `trigger`. Those 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. Each `end` then counts only the layers before it, and a scene enclosed by an earlier one no longer pushes points outside that scene.
|
|
485
509
|
|
|
486
|
-
|
|
510
|
+
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.
|
|
487
511
|
|
|
488
512
|
> 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.
|
|
489
513
|
>
|
|
@@ -509,14 +533,15 @@ sticky.createOverlapScroll({
|
|
|
509
533
|
- `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
|
|
510
534
|
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
|
|
511
535
|
- 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))
|
|
536
|
+
- 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`
|
|
512
537
|
- `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
|
|
513
538
|
- `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
|
|
514
539
|
- 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
|
|
515
540
|
- ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
|
|
516
541
|
- 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))
|
|
517
|
-
- A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can
|
|
542
|
+
- 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))
|
|
518
543
|
- 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
|
|
519
|
-
- If
|
|
544
|
+
- If Scene layers' `endTrigger`s depend on each other in a way that never settles, the layers resolve in dependency order (see [End syntax](#end-syntax)). `refresh()` can still throw in rare arrangements, such as a scene whose `end` counts one with an absolute `start` only while a third scene's window closes before it, and that third scene's `start` moves with the first scene's dwell. Two layers whose ends each move the other settle on the one answer they share
|
|
520
545
|
- `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
|
|
521
546
|
- Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
|
|
522
547
|
- 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))
|