sticky-scroll-trigger 0.7.0 → 0.9.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
|
@@ -36,7 +36,7 @@ npm install gsap sticky-scroll-trigger
|
|
|
36
36
|
For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
|
|
37
37
|
|
|
38
38
|
```html
|
|
39
|
-
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger/dist/StickyScrollTrigger.global.min.js"></script>
|
|
39
|
+
<script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.9.0/dist/StickyScrollTrigger.global.min.js"></script>
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
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.
|
|
@@ -147,6 +147,8 @@ Call them on the instance (`sticky.createStickyTrigger(...)`) rather than destru
|
|
|
147
147
|
|
|
148
148
|
Like `root`, every `trigger`/`endTrigger`/`cover` option below also accepts a CSS selector string (in addition to an `HTMLElement`), resolved via `document.querySelector`, the same as GSAP ScrollTrigger's own `trigger`/`endTrigger`. Throws an error if the selector matches no elements.
|
|
149
149
|
|
|
150
|
+
`trigger` is required by every method here, unlike GSAP's own: a plain ScrollTrigger can leave it out and take its range from `start`/`end` alone. Every method here either wraps `trigger` or measures from it, so there is nothing to work from without one.
|
|
151
|
+
|
|
150
152
|
### `createStickyTrigger(options)`
|
|
151
153
|
|
|
152
154
|
Registers a layer that pins a scene and advances its effect, and returns `ScrollTrigger.Vars`. Pass the return value as a tween's `scrollTrigger`. ScrollTrigger options (`scrub`, `markers`, `onUpdate`, etc.) pass through as-is, except for the exclusions in the table below.
|
|
@@ -178,6 +180,8 @@ Registers an overlap-scroll effect (`trigger` gets pinned while its siblings fro
|
|
|
178
180
|
| `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" |
|
|
179
181
|
| `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax |
|
|
180
182
|
|
|
183
|
+
`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
|
+
|
|
181
185
|
`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.
|
|
182
186
|
|
|
183
187
|
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.
|
|
@@ -260,13 +264,13 @@ ScrollTrigger.create(
|
|
|
260
264
|
sticky.refresh();
|
|
261
265
|
```
|
|
262
266
|
|
|
263
|
-
| option | default
|
|
264
|
-
| ------------ |
|
|
265
|
-
| `trigger` | (required)
|
|
266
|
-
| `start` | `'top top'`
|
|
267
|
-
| `top` | `0`
|
|
268
|
-
| `endTrigger` |
|
|
269
|
-
| `end` | `'
|
|
267
|
+
| option | default | description |
|
|
268
|
+
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
269
|
+
| `trigger` | (required) | The element to pin and show |
|
|
270
|
+
| `start` | `'top top'` | Where `trigger` lands in the viewport while pinned, in [position syntax](#position-syntax), so the element's own side counts too (`'bottom bottom'` rests it against the viewport's bottom edge) |
|
|
271
|
+
| `top` | `0` | A px distance from the viewport's top edge, as a plain number. `top: 20` is `start: 'top 20px'` |
|
|
272
|
+
| `endTrigger` | `trigger` | Reference element for releasing the pin |
|
|
273
|
+
| `end` | `'bottom top'` | Which clause of `endTrigger` releases the pin (standard GSAP [position syntax](#position-syntax)) |
|
|
270
274
|
|
|
271
275
|
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.
|
|
272
276
|
|
|
@@ -274,6 +278,10 @@ That's why `start` throws on an [absolute scroll position](#absolute-scroll-posi
|
|
|
274
278
|
|
|
275
279
|
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.
|
|
276
280
|
|
|
281
|
+
`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.
|
|
282
|
+
|
|
283
|
+
`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.
|
|
284
|
+
|
|
277
285
|
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: ...`).
|
|
278
286
|
|
|
279
287
|
See the repository's `ARCHITECTURE.md` ("Why `createStickyPin` is unaffected by nested-sticky lag") for why the lag never applies here, and why `trigger` needs two nested wrapper divs.
|
|
@@ -296,12 +304,14 @@ gsap.to(plainBox, {
|
|
|
296
304
|
});
|
|
297
305
|
```
|
|
298
306
|
|
|
299
|
-
| option | default
|
|
300
|
-
| ------------ |
|
|
301
|
-
| `trigger` | (required)
|
|
302
|
-
| `start` |
|
|
303
|
-
| `end` |
|
|
304
|
-
| `endTrigger` | `trigger`
|
|
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) |
|
|
313
|
+
|
|
314
|
+
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.
|
|
305
315
|
|
|
306
316
|
This does not register a layer, so `refresh()` does not manage it. It shares the same rejected-option table as [`createStickyTrigger`](#createstickytriggeroptions) (no pin-family options, no `horizontal`/`scroller`/`containerAnimation`).
|
|
307
317
|
|
|
@@ -415,7 +425,7 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
415
425
|
| token | example | meaning |
|
|
416
426
|
| ----------- | --------------------------- | ------------------------------------------------------------- |
|
|
417
427
|
| keyword | `top` / `center` / `bottom` | 0% / 50% / 100% |
|
|
418
|
-
| bare number | `80` / `80px`
|
|
428
|
+
| bare number | `80` / `80px` / `-50` | ± px from the reference point (matches GSAP: only `%` scales) |
|
|
419
429
|
| percentage | `80%` | 80% of the target's height |
|
|
420
430
|
| px offset | `center+=50` / `top-=20` | ± px from the reference point |
|
|
421
431
|
| % offset | `top+=10%` | ± (relative to the target's height) |
|
|
@@ -426,7 +436,9 @@ Pinning decouples an element's position in the document from the scroll position
|
|
|
426
436
|
start: () => `center center+=${getHeaderHeight() / 2}`,
|
|
427
437
|
```
|
|
428
438
|
|
|
429
|
-
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.
|
|
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. 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`.
|
|
440
|
+
|
|
441
|
+
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.
|
|
430
442
|
|
|
431
443
|
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`.
|
|
432
444
|
|
|
@@ -436,7 +448,7 @@ GSAP passes the `ScrollTrigger` instance to its own function-valued `start`/`end
|
|
|
436
448
|
|
|
437
449
|
### Absolute scroll position
|
|
438
450
|
|
|
439
|
-
|
|
451
|
+
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`.
|
|
440
452
|
|
|
441
453
|
`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, ...)`.
|
|
442
454
|
|
|
@@ -452,7 +464,7 @@ If the entire value is just a number (a plain JS number, or a string that's noth
|
|
|
452
464
|
|
|
453
465
|
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.
|
|
454
466
|
|
|
455
|
-
"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).
|
|
467
|
+
"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.
|
|
456
468
|
|
|
457
469
|
| example | meaning |
|
|
458
470
|
| -------------------------------- | ------------------------------------- |
|
|
@@ -471,6 +483,10 @@ sticky.createStickyTrigger({
|
|
|
471
483
|
});
|
|
472
484
|
```
|
|
473
485
|
|
|
486
|
+
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.
|
|
487
|
+
|
|
488
|
+
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
|
+
|
|
474
490
|
If `endTrigger` points to another registered layer, its position is resolved using the same computation this module already does for that layer. A forward reference (pointing to a layer later in DOM order) only works from `createOverlapScroll`'s cover layer, which adds no padding and so doesn't depend on its own dwell. A `createStickyTrigger` Scene layer throws immediately instead: its own dwell padding pushes down everything after it, so the reference would depend on that dwell and never converge.
|
|
475
491
|
|
|
476
492
|
For an unregistered `endTrigger`, its raw DOM position is measured directly, then adjusted by the dwell of every registered Scene layer structurally positioned before it, including ones registered after this call, if their `trigger` sits between this layer's `trigger` and `endTrigger`.
|
|
@@ -500,7 +516,7 @@ sticky.createOverlapScroll({
|
|
|
500
516
|
- `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
|
|
501
517
|
- 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))
|
|
502
518
|
- `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
|
|
503
|
-
- `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
|
|
519
|
+
- `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
|
|
504
520
|
- 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
|
|
505
521
|
- ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
|
|
506
522
|
- 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))
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/*!
|
|
2
2
|
* @license
|
|
3
|
-
* StickyScrollTrigger v0.
|
|
3
|
+
* StickyScrollTrigger v0.9.0
|
|
4
4
|
* Copyright (c) 2026 Kuninori Ogino
|
|
5
5
|
* Released under the MIT License
|
|
6
6
|
* https://github.com/kuninori-ogino/sticky-scroll-trigger
|
|
@@ -17,8 +17,8 @@ export declare interface CreateOverlapScrollOptions extends PassThroughVars {
|
|
|
17
17
|
|
|
18
18
|
export declare interface CreateResolvedTriggerOptions extends PassThroughVars {
|
|
19
19
|
trigger: string | HTMLElement;
|
|
20
|
-
start
|
|
21
|
-
end
|
|
20
|
+
start?: PositionInput;
|
|
21
|
+
end?: PositionInput;
|
|
22
22
|
endTrigger?: string | HTMLElement;
|
|
23
23
|
}
|
|
24
24
|
|
|
@@ -26,7 +26,7 @@ export declare interface CreateStickyPinOptions extends PassThroughVars {
|
|
|
26
26
|
trigger: string | HTMLElement;
|
|
27
27
|
start?: PositionInput;
|
|
28
28
|
top?: number | (() => number);
|
|
29
|
-
endTrigger
|
|
29
|
+
endTrigger?: string | HTMLElement;
|
|
30
30
|
end?: PositionInput;
|
|
31
31
|
}
|
|
32
32
|
|