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 | description |
264
- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
265
- | `trigger` | (required) | The element to pin and show |
266
- | `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) |
267
- | `top` | `0` | A px distance from the viewport's top edge, as a plain number. `top: 20` is `start: 'top 20px'` |
268
- | `endTrigger` | (required) | Reference element for releasing the pin |
269
- | `end` | `'top top'` | Which clause of `endTrigger` releases the pin (standard GSAP [position syntax](#position-syntax)) |
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 | description |
300
- | ------------ | ---------- | ------------------------------------------------------------------------------------------ |
301
- | `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger` |
302
- | `start` | (required) | [Position syntax](#position-syntax), resolved relative to `trigger` |
303
- | `end` | (required) | [Position syntax](#position-syntax), resolved relative to `endTrigger` |
304
- | `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split) |
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` | 80px from the reference point (matches GSAP: only `%` scales) |
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
- If the entire value is just a number (a plain JS number, or a string that's nothing but digits, with no keyword, second token, or `%`/`px` suffix), GSAP treats it as an absolute scroll position rather than a clause, and ignores the reference element entirely (`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`.
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 wraps `trigger` in a `height:0`, `contain:layout` box, which would pull the container and the layers' dwell padding out of the flow
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.7.0
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: PositionInput;
21
- end: PositionInput;
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: string | HTMLElement;
29
+ endTrigger?: string | HTMLElement;
30
30
  end?: PositionInput;
31
31
  }
32
32