sticky-scroll-trigger 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kuninori Ogino
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,404 @@
1
+ # StickyScrollTrigger
2
+
3
+ A ScrollTrigger helper that uses native `position:sticky` instead of GSAP pinning.
4
+
5
+ > ScrollTrigger is part of GSAP®, a Webflow product. This project is an independent, unofficial helper and is not affiliated with or endorsed by Webflow.
6
+
7
+ The only dependency is GSAP's ScrollTrigger types.
8
+
9
+ - Pin multiple scenes in sequence, sharing a single container (no gap opens up from adjacent elements scrolling away while one is pinned)
10
+ - Pinning is handled 100% by the browser's `position:sticky`; GSAP only tweens the effect's own properties while the freeze window is active
11
+ - The "section below rises up and covers the section above" effect (overlap scroll) is achieved without changing document height
12
+
13
+ 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.
14
+
15
+ ## Requirements
16
+
17
+ | requirement | description |
18
+ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
+ | GSAP | 3.x, with the `ScrollTrigger` plugin already registered via `gsap.registerPlugin` |
20
+ | TypeScript | Optional. The published `.d.ts` uses GSAP's global types (`ScrollTrigger.Vars`); plain JavaScript projects can `import` the same `dist/` build without them |
21
+ | Browser | Must support `position:sticky` (no `overflow:hidden`/`clip` on any ancestor of a pinned element) |
22
+ | Scroll direction | Vertical scrolling only (`horizontal` is not supported) |
23
+ | Module system | ESM only (`import`) or a `<script>` tag via the global build; CommonJS (`require`) is not supported |
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ npm install gsap sticky-scroll-trigger
29
+ ```
30
+
31
+ `gsap` (with its `ScrollTrigger` plugin) is a peer dependency; register the plugin yourself (see [Usage](#usage) below).
32
+
33
+ For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
34
+
35
+ ```html
36
+ <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger/dist/StickyScrollTrigger.global.min.js"></script>
37
+ ```
38
+
39
+ 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.
40
+
41
+ ## Usage
42
+
43
+ Pick a single "shared container" that wraps all the scenes you want to pin, and create a `StickyScrollTrigger` instance for its selector.
44
+
45
+ ```html
46
+ <div class="container">
47
+ <div class="container__inner">
48
+ <section class="scene">...</section>
49
+ <section class="filler">...</section>
50
+ <section class="overlapScroll__trigger">...</section>
51
+ <section class="overlapScroll__cover">...</section>
52
+ </div>
53
+ </div>
54
+ ```
55
+
56
+ ```ts
57
+ import gsap from "gsap";
58
+ import { ScrollTrigger } from "gsap/ScrollTrigger";
59
+ import StickyScrollTrigger from "sticky-scroll-trigger";
60
+
61
+ gsap.registerPlugin(ScrollTrigger);
62
+
63
+ const sticky = new StickyScrollTrigger(".container__inner");
64
+
65
+ // Scene effect. This just builds and returns the Vars passed to
66
+ // scrollTrigger, so writing the tween itself is just ordinary GSAP.
67
+ gsap.fromTo(
68
+ scene,
69
+ { opacity: 0 },
70
+ {
71
+ opacity: 1,
72
+ scrollTrigger: sticky.createStickyTrigger({
73
+ trigger: scene,
74
+ start: "center center",
75
+ end: "+=100%",
76
+ scrub: true,
77
+ }),
78
+ },
79
+ );
80
+
81
+ // Overlap scroll effect. No tween involved, so pass it straight to ScrollTrigger.create().
82
+ ScrollTrigger.create(
83
+ sticky.createOverlapScroll({ trigger: ".trigger", cover: ".cover" }),
84
+ );
85
+
86
+ // Call once, after all registrations are done.
87
+ sticky.refresh();
88
+ ```
89
+
90
+ Registration order doesn't matter. `refresh()` sorts trigger elements by DOM order internally and builds the nesting from that, so you're free to register different effect types in separate loops.
91
+
92
+ ### Calling refresh
93
+
94
+ `createStickyTrigger`/`createOverlapScroll` do not call `refresh()` automatically. Call it once after registration. Resize/load are already covered via GSAP's `refreshInit`, so manual calls are mainly for non-resize layout changes (for example, content height changes).
95
+
96
+ `debounce` isn't provided by this library or GSAP. Bring your own (e.g. lodash's `debounce`) or use a minimal version like this:
97
+
98
+ ```ts
99
+ const debounce = <Args extends unknown[]>(
100
+ fn: (...args: Args) => void,
101
+ wait: number,
102
+ ) => {
103
+ let timer: ReturnType<typeof setTimeout>;
104
+ return (...args: Args) => {
105
+ clearTimeout(timer);
106
+ timer = setTimeout(() => fn(...args), wait);
107
+ };
108
+ };
109
+
110
+ const debouncedRefresh = debounce(() => {
111
+ ScrollTrigger.refresh(); // runs refresh() first, via refreshInit
112
+ }, 100);
113
+
114
+ if (document.scrollingElement) {
115
+ new ResizeObserver(() => debouncedRefresh()).observe(
116
+ document.scrollingElement,
117
+ );
118
+ }
119
+ ```
120
+
121
+ Order matters: `refresh()` must run before `ScrollTrigger.refresh()`, or GSAP may read stale freeze-window values.
122
+
123
+ This binding is automatic as soon as you register at least one `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` result with ScrollTrigger.
124
+
125
+ If you only use `createResolvedTrigger`/`resolveScrollPosition`, auto-binding has nothing to attach to, so bind manually:
126
+
127
+ ```ts
128
+ ScrollTrigger.addEventListener("refreshInit", () => sticky.refresh());
129
+ ```
130
+
131
+ Avoid debounce logic that assumes it runs before GSAP's 200ms delay. Use `refreshInit` binding.
132
+
133
+ ## API
134
+
135
+ ### `new StickyScrollTrigger(root)`
136
+
137
+ Creates an instance that treats `root` (a selector string or `HTMLElement`) as the shared container, exposing `createStickyTrigger`, `createOverlapScroll`, `createStickyPin`, `createResolvedTrigger`, `resolveScrollPosition`, `refresh`, and `destroy` as instance methods. Throws if the shared container can't be found. The class itself also exposes a static [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances) method, for resolving a position across more than one instance.
138
+
139
+ These are ordinary instance methods, not standalone functions, so always call them on the instance (`sticky.createStickyTrigger(...)`) rather than destructuring them out; a destructured method loses its `this` binding when called.
140
+
141
+ 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.
142
+
143
+ ### `createStickyTrigger(options)`
144
+
145
+ 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.
146
+
147
+ | rejected option | reason |
148
+ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
149
+ | `trigger` / `start` / `end` / `endTrigger` | This module derives these itself from the freeze window |
150
+ | `pin` / `pinSpacing` / `anticipatePin` / `pinnedContainer` / `pinReparent` / `pinSpacer` / `pinType` | Pinning is handled by `position:sticky`, not GSAP pinning, so these have no effect |
151
+ | `horizontal` / `scroller` / `containerAnimation` | This module assumes vertical, window-based scrolling; setting these shifts positions |
152
+
153
+ 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. Tracking of the freeze window (`start`/`end`) is independent of this flag, so setting `invalidateOnRefresh: false` will not break it. Explicit values are respected.
154
+
155
+ | option | default | description |
156
+ | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
157
+ | `trigger` | (required) | The scene element to pin and animate. Must be inside the shared container |
158
+ | `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) |
159
+ | `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 |
160
+ | `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax. Must be inside the shared container (see below) |
161
+
162
+ ### `createOverlapScroll(options)`
163
+
164
+ Registers an overlap-scroll effect (`trigger` gets pinned while its siblings from `cover` onward scroll normally and rise up to cover it) and returns `ScrollTrigger.Vars`. No tween or dwell spacer is created. Since the return value only describes the freeze window, the effect works even without passing it to `ScrollTrigger.create()`, unless you need `markers` or callbacks.
165
+
166
+ | option | default | description |
167
+ | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
168
+ | `trigger` | (required) | The element that gets pinned and covered. Must be a direct child of the shared container |
169
+ | `cover` | `trigger.nextElementSibling` | The first element of the covering side; this and all following siblings cover together. Must share the same parent as `trigger` |
170
+ | `start` | `'bottom bottom'` | Pinned position of `trigger`. See [position syntax](#position-syntax). Unlike `createStickyTrigger`'s `start`, this doesn't support an absolute scroll position (a bare number): it throws instead |
171
+ | `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" |
172
+ | `endTrigger` | `trigger` | Reference element when `end` uses position-clause syntax |
173
+
174
+ `createOverlapScroll` adjusts `position`/`z-index` on the covering side only when needed, never overrides explicit values, and restores its changes on GSAP `kill()`.
175
+
176
+ ### `createStickyPin(options)`
177
+
178
+ Pins small elements (badges, labels, etc.) with plain `position:sticky` (pinning handled entirely by CSS, not GSAP). Pinning starts when `trigger` reaches its sticky position and releases when `endTrigger` reaches the `end` clause. This is independent of Scene/Cover layers and works the same inside or outside the shared container.
179
+
180
+ Because pinning is handled by CSS, the returned `ScrollTrigger.Vars` does not define GSAP `start`/`end`; it exists for hooks such as `onKill`/`onRefreshInit`. Pass it to `ScrollTrigger.create()` if you want automatic cleanup and auto refresh-binding.
181
+
182
+ ```ts
183
+ const sticky = new StickyScrollTrigger(".container__inner");
184
+
185
+ // badge can be inside the shared container. Stays pinned until sectionEnd is reached.
186
+ // getHeaderHeight() is your own function (not part of this library) that returns the
187
+ // current header height in px.
188
+ ScrollTrigger.create(
189
+ sticky.createStickyPin({
190
+ trigger: ".badge",
191
+ top: () => getHeaderHeight() + 20,
192
+ endTrigger: ".sectionEnd",
193
+ end: "top top",
194
+ }),
195
+ );
196
+
197
+ sticky.refresh();
198
+ ```
199
+
200
+ | option | default | description |
201
+ | ------------ | ----------- | ------------------------------------------------------------------------------------------------- |
202
+ | `trigger` | (required) | The element to pin and show |
203
+ | `top` | `0` | Distance from the top of the viewport while pinned (this is literally sticky's `top`) |
204
+ | `endTrigger` | (required) | Reference element for releasing the pin |
205
+ | `end` | `'top top'` | Which clause of `endTrigger` releases the pin (standard GSAP [position syntax](#position-syntax)) |
206
+
207
+ 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: ...`).
208
+
209
+ See the repository's `ARCHITECTURE.md` ("Why `createStickyPin` is unaffected by nested-sticky lag") for why `createStickyPin` is completely unaffected by nested-sticky lag, and why `trigger` needs to be wrapped in two nested divs.
210
+
211
+ ### `createResolvedTrigger(options)`
212
+
213
+ A thin wrapper that calls [`resolveScrollPosition`](#resolvescrollpositionelement-position) for `trigger`/`start`/`end` together and assembles the result into `ScrollTrigger.Vars`. If you just want to place a plain ScrollTrigger on an element inside the shared container, start here.
214
+
215
+ ```ts
216
+ const sticky = new StickyScrollTrigger(".container__inner");
217
+
218
+ gsap.to(plainBox, {
219
+ autoAlpha: 1,
220
+ scrollTrigger: sticky.createResolvedTrigger({
221
+ trigger: plainBox,
222
+ start: "top 80%",
223
+ end: "top 30%",
224
+ scrub: true,
225
+ }),
226
+ });
227
+ ```
228
+
229
+ | option | default | description |
230
+ | ------------ | ---------- | ------------------------------------------------------------------------------------------ |
231
+ | `trigger` | (required) | Reference element for `start`. Also passed through as-is to GSAP's `scrollTrigger.trigger` |
232
+ | `start` | (required) | [Position syntax](#position-syntax), resolved relative to `trigger` |
233
+ | `end` | (required) | [Position syntax](#position-syntax), resolved relative to `endTrigger` |
234
+ | `endTrigger` | `trigger` | Reference element for `end` (same idea as GSAP's standard `trigger`/`endTrigger` split) |
235
+
236
+ 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`).
237
+
238
+ If you need different reference elements or custom progress logic, use `resolveScrollPosition` directly.
239
+
240
+ ### `resolveScrollPosition(element, position)`
241
+
242
+ 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.
243
+
244
+ ```ts
245
+ const sticky = new StickyScrollTrigger(".container__inner");
246
+
247
+ // An element inside the shared container that isn't registered with
248
+ // createStickyTrigger/createOverlapScroll
249
+ ScrollTrigger.create({
250
+ trigger: ".plainBox",
251
+ start: () => sticky.resolveScrollPosition(".plainBox", "top 80%"),
252
+ end: () => sticky.resolveScrollPosition(".plainBox", "top 30%"),
253
+ scrub: true,
254
+ });
255
+ ```
256
+
257
+ Call this after `refresh()`. If passed as a function to `start`/`end`, it is re-evaluated on each GSAP refresh.
258
+
259
+ `position` also accepts GSAP's [`'max'` keyword](#end-syntax) (e.g. `resolveScrollPosition(".plainBox", "max")`), which ignores `element` entirely and returns the scroller's max scroll position.
260
+
261
+ Using it with `pin: true` is discouraged because the element can jump when pinning starts. If you only need pinning, use [`createStickyPin`](#createstickypinoptions). See the repository's `ARCHITECTURE.md` ("Why `resolveScrollPosition` corrects for lag") for details.
262
+
263
+ Only the dwell of Scene layers registered via `createStickyTrigger` is accumulated here (`createOverlapScroll` never changes the document height, so it doesn't contribute to the lag).
264
+
265
+ For a target that might belong to a _different_ instance than the one at hand (e.g. a same-page anchor link, where you don't know in advance which instance's shared container it lives in), use the static [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances) below instead.
266
+
267
+ ### `StickyScrollTrigger.getScrollTop(element, instances)`
268
+
269
+ A static method, call it on the class itself (`StickyScrollTrigger.getScrollTop(...)`), not on an instance. Returns the absolute scroll position (px) at which `element`'s own top edge reaches the viewport's top edge (`'top top'`), picking whichever of the given `instances` actually has `element` inside its shared container. Applying the wrong instance's dwell to a target it never delayed would corrupt the result, the same way plain [`resolveScrollPosition`](#resolvescrollpositionelement-position) warns against.
270
+
271
+ ```ts
272
+ import StickyScrollTrigger from "sticky-scroll-trigger";
273
+
274
+ const stickyA = new StickyScrollTrigger(".sectionA");
275
+ const stickyB = new StickyScrollTrigger(".sectionB");
276
+
277
+ document.querySelectorAll('a[href^="#"]').forEach((anchor) => {
278
+ anchor.addEventListener("click", (event) => {
279
+ const target = document.getElementById(anchor.hash.slice(1));
280
+
281
+ if (!target) return;
282
+
283
+ event.preventDefault();
284
+ window.scrollTo({
285
+ top: StickyScrollTrigger.getScrollTop(target, [stickyA, stickyB]),
286
+ behavior: "smooth",
287
+ });
288
+ });
289
+ });
290
+ ```
291
+
292
+ An `element` outside every given instance's shared container is measured directly (no dwell to correct for), so passing every `StickyScrollTrigger` instance on the page is always safe, whether or not the target actually belongs to any of them.
293
+
294
+ ### `refresh()`
295
+
296
+ Recomputes each layer's sticky `top`, dwell spacer height, and freeze window (`start`/`end`). It also rebuilds nested DOM when triggers are added, removed, or reordered. If nothing has changed, it does not rebuild.
297
+
298
+ Kill-driven teardown/rebuild is deferred to a microtask and coalesced per task. This DOM move can reload `<iframe>` elements or drop focus for focused inputs inside the managed container. This behavior runs on every kill or relevant layout change and cannot be disabled, so be careful when placing iframes or focus-sensitive inputs under the controller.
299
+
300
+ If surviving layers' freeze windows change after kill, GSAP's cached `start`/`end` values are synced internally.
301
+
302
+ ### `destroy()`
303
+
304
+ Tears down the controller, restores the original DOM layout, and reverts z-order changes from `createOverlapScroll`. This is also the only entry point that can clean up cover layers that were never passed to `ScrollTrigger.create()`.
305
+
306
+ It only cleans up DOM/styles managed by this module. You still need to kill active ScrollTrigger instances yourself. After `destroy()`, `createStickyTrigger`/`createOverlapScroll` throw and `refresh()` is a no-op. Calling `destroy()` twice is safe.
307
+
308
+ ## Position syntax
309
+
310
+ `start` (and `end`'s position-clause form) accepts GSAP's standard `"element-side viewport-side"` syntax. With only one clause, the viewport side defaults to `top` (`"center"` is equivalent to `"center top"`, not `"center center"`). You can also pass a function that returns a string, or for the absolute scroll position case below, a number. It's re-evaluated on every `refresh()`, which is handy for reflecting variable values like header height.
311
+
312
+ | token | example | meaning |
313
+ | ----------- | --------------------------- | ------------------------------------------------------------- |
314
+ | keyword | `top` / `center` / `bottom` | 0% / 50% / 100% |
315
+ | bare number | `80` / `80px` | 80px from the reference point (matches GSAP: only `%` scales) |
316
+ | percentage | `80%` | 80% of the target's height |
317
+ | px offset | `center+=50` / `top-=20` | ± px from the reference point |
318
+ | % offset | `top+=10%` | ± (relative to the target's height) |
319
+
320
+ ```ts
321
+ // Center the scene within the visible area, excluding a 56px header.
322
+ // getHeaderHeight() is your own function (not part of this library).
323
+ start: () => `center center+=${getHeaderHeight() / 2}`,
324
+ ```
325
+
326
+ 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.
327
+
328
+ 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`.
329
+
330
+ ### Absolute scroll position
331
+
332
+ 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, ignoring 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`.
333
+
334
+ `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, ...)`.
335
+
336
+ `'500 top'` (two tokens) and `'500px'` (a suffix) don't qualify for this; they resolve via the bare-number _offset_ row in the table above instead, same as GSAP.
337
+
338
+ > [`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.
339
+
340
+ ## End syntax
341
+
342
+ `end` auto-detects between an absolute scroll position, dwell distance, GSAP's `'max'` keyword, and a position clause.
343
+
344
+ 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.
345
+
346
+ "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).
347
+
348
+ | example | meaning |
349
+ | -------------------------------- | ------------------------------------- |
350
+ | `500` / `'500'` | End at absolute scroll position 500px |
351
+ | `'+=500'` / `'+=500px'` | Pin for 500px |
352
+ | `'+=100%'` | Pin for one viewport height |
353
+ | `() => window.innerHeight * 1.5` | Functions are also accepted |
354
+
355
+ "Position clause": ends the freeze window at the absolute scroll position where the given clause of `endTrigger` (defaults to `trigger` itself) reaches the given clause of the viewport, the same idea as GSAP's own `end`. This also covers offset-only notation with no keyword before it, resolved against `endTrigger`'s own dimensions instead of the viewport's: `'-=500'` means 500px before `endTrigger`'s top, and `'+100%'`/`'50%'` mean a fraction of `endTrigger`'s own height, not a dwell distance.
356
+
357
+ ```ts
358
+ sticky.createStickyTrigger({
359
+ trigger: ".scene",
360
+ end: "bottom top",
361
+ endTrigger: ".nextSection",
362
+ });
363
+ ```
364
+
365
+ If `endTrigger` points to another registered layer, its position is resolved using the same computation this module already does for that layer. Forward references (pointing to a layer registered later in DOM order) only work when the referencing layer is `createOverlapScroll`'s cover layer, since it adds no padding and so doesn't depend on its own dwell.
366
+
367
+ A `createStickyTrigger` Scene layer can't forward-reference a later layer this way: its own dwell padding always precedes and pushes down everything after it, so the reference would depend on its own dwell and never converge. It throws immediately instead of trying.
368
+
369
+ 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`.
370
+
371
+ > 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.
372
+ >
373
+ > `createOverlapScroll` isn't subject to this restriction.
374
+
375
+ "`'max'` keyword": GSAP's own `end: 'max'` notation, the scroller's max scroll position, optionally offset (`'max-=100'`, `'max+=10%'`). Ignores `endTrigger` entirely.
376
+
377
+ ```ts
378
+ sticky.createOverlapScroll({
379
+ trigger: ".trigger",
380
+ cover: ".cover",
381
+ end: "max",
382
+ }); // pin until the very bottom of the page
383
+ ```
384
+
385
+ `'max'` is only supported by [`createOverlapScroll`](#createoverlapscrolloptions) and [`resolveScrollPosition`](#resolvescrollpositionelement-position)/[`createResolvedTrigger`](#createresolvedtriggeroptions). `createStickyTrigger` and `createStickyPin` throw if `end` is `'max'`, because their own dwell padding or pin spacer adds to the document height that `'max'` measures: the freeze window would depend on itself and never settle, growing the page a little more on every `refresh()`. GSAP only defines `'max'` for `end`, not `start`, so this module doesn't support it for `start` either.
386
+
387
+ ## Constraints and caveats
388
+
389
+ - The structure directly under the shared container changes because of the added wrapper elements. Direct-child selectors like `.container__inner > .scene`, `:nth-child()`, adjacent-sibling selectors (`+`/`~`), and flex/grid layout on the shared container itself may break across the wrapper boundary
390
+ - `position:sticky` doesn't work if any ancestor of the pinned target has `overflow:hidden`/`clip`
391
+ - `createOverlapScroll`'s `trigger` and `cover` must be siblings sharing the same parent
392
+ - ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
393
+ - A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer that comes later in DOM order: it throws immediately, since the Scene layer's own dwell always precedes that later layer's position. `createOverlapScroll`'s cover layer isn't subject to this; it creates no padding, so a forward reference resolves normally
394
+ - 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
395
+ - If several layers' unregistered or cover-layer `endTrigger`s structurally depend on each other's dwell/position in a cycle (each layer's end depends on a layer whose own end depends back on it), `refresh()` throws instead of settling on an incorrect value
396
+ - `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` for the same reason (their own padding/spacer would depend on itself); use `createOverlapScroll` instead
397
+ - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
398
+ - 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))
399
+ - Resizes from mobile browsers showing/hiding their address bar are absorbed automatically (see the repository's `ARCHITECTURE.md`, "Two-pass position measurement"), but other causes like `visualViewport` zoom are not handled
400
+ - Don't nest one `StickyScrollTrigger` instance's shared container inside another's: once a target sits inside more than one, [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances)'s ownership check picks whichever instance is listed first, and neither instance's own dwell alone is actually correct for it
401
+
402
+ ## License
403
+
404
+ [MIT](LICENSE)
@@ -0,0 +1,63 @@
1
+ /*!
2
+ * @license
3
+ * StickyScrollTrigger v0.2.0
4
+ * Copyright (c) 2026 Kuninori Ogino
5
+ * Released under the MIT License
6
+ * https://github.com/kuninori-ogino/sticky-scroll-trigger
7
+ */
8
+ /// <reference types="gsap" />
9
+
10
+ export declare interface CreateOverlapScrollOptions extends PassThroughVars {
11
+ trigger: string | HTMLElement;
12
+ cover?: string | HTMLElement;
13
+ start?: PositionInput;
14
+ end?: EndInput | null;
15
+ endTrigger?: string | HTMLElement;
16
+ }
17
+
18
+ export declare interface CreateResolvedTriggerOptions extends PassThroughVars {
19
+ trigger: string | HTMLElement;
20
+ start: PositionInput;
21
+ end: PositionInput;
22
+ endTrigger?: string | HTMLElement;
23
+ }
24
+
25
+ export declare interface CreateStickyPinOptions extends PassThroughVars {
26
+ trigger: string | HTMLElement;
27
+ top?: number | (() => number);
28
+ endTrigger: string | HTMLElement;
29
+ end?: PositionInput;
30
+ }
31
+
32
+ export declare interface CreateStickyTriggerOptions extends PassThroughVars {
33
+ trigger: string | HTMLElement;
34
+ start?: PositionInput;
35
+ end?: EndInput;
36
+ endTrigger?: string | HTMLElement;
37
+ }
38
+
39
+ export declare type EndInput = EndValue | (() => EndValue);
40
+
41
+ export declare type EndValue = string | number;
42
+
43
+ declare type PassThroughVars = Omit<ScrollTrigger.Vars, 'trigger' | 'start' | 'end' | 'endTrigger' | 'pin' | 'pinSpacing' | 'anticipatePin' | 'pinnedContainer' | 'pinReparent' | 'pinSpacer' | 'pinType' | 'horizontal' | 'scroller' | 'containerAnimation'>;
44
+
45
+ export declare type PositionInput = PositionValue | (() => PositionValue);
46
+
47
+ declare type PositionValue = string | number;
48
+
49
+ declare class StickyScrollTrigger {
50
+ #private;
51
+ constructor(root: string | HTMLElement);
52
+ refresh(): void;
53
+ createStickyTrigger({ trigger: triggerInput, start, end, endTrigger: endTriggerInput, onKill, ...rest }: CreateStickyTriggerOptions): ScrollTrigger.Vars;
54
+ createOverlapScroll({ trigger: triggerInput, cover, start, end, endTrigger: endTriggerInput, onKill, ...rest }: CreateOverlapScrollOptions): ScrollTrigger.Vars;
55
+ createStickyPin({ trigger: triggerInput, top, endTrigger: endTriggerInput, end, onKill, ...rest }: CreateStickyPinOptions): ScrollTrigger.Vars;
56
+ resolveScrollPosition(elementInput: string | HTMLElement, position: PositionInput): number;
57
+ static getScrollTop(elementInput: string | HTMLElement, instances: readonly StickyScrollTrigger[]): number;
58
+ createResolvedTrigger({ trigger: triggerInput, start, end, endTrigger: endTriggerInput, ...rest }: CreateResolvedTriggerOptions): ScrollTrigger.Vars;
59
+ destroy(): void;
60
+ }
61
+ export default StickyScrollTrigger;
62
+
63
+ export { }