morphing-scroll 1.5.20 → 1.5.22

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.
Files changed (2) hide show
  1. package/README.md +974 -1005
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -35,728 +35,711 @@ npm install morphing-scroll
35
35
 
36
36
  - ### Props:
37
37
 
38
+ <div>
39
+
38
40
  #### GENERAL SETTINGS:
39
41
 
40
- <details>
41
- <summary><strong><code>className</code></strong>: <em>Additional classes for the component.</em></summary><br />
42
- <ul>
43
- <strong>Type:</strong> string<br />
44
- <br />
45
- <strong>Description:</strong> <em><br />
46
- This parameter allows you to apply custom CSS classes to the <code>MorphScroll</code> component, enabling further customization and styling to fit your design needs.</em><br />
47
- <br />
48
- <strong>Example:</strong>
49
-
50
- ```tsx
51
- <MorphScroll
52
- className="your-class"
53
- // another props
54
- >
55
- {children}
56
- </MorphScroll>
57
- ```
58
-
59
- </ul>
60
- </details>&nbsp;
61
- <h2></h2>&nbsp;
62
- <details>
63
- <summary><strong><code>children</code></strong>: <em>Custom user content.</em></summary><br />
64
- <ul>
65
- <strong>Type:</strong> React.ReactNode<br />
66
- <br />
67
- <strong>Description:</strong> <em><br />
68
- This is where you can pass your list elements.<br />
69
- Make sure to provide unique keys for each list item, as per React's rules. The <code>MorphScroll</code> component ensures that the cells it generates will use the same keys as your list items, allowing it to render the correct cells for the current list.<br />
70
- Additionally, <code>MorphScroll</code> handles a passed <code>null</code> value the same way as <code>undefined</code>, rendering nothing in both cases.</em><br />
71
- <br />
72
- <strong>Example:</strong>
73
-
74
- ```tsx
75
- <MorphScroll
76
- // props
77
- >
78
- {children}
79
- </MorphScroll>
80
- ```
81
-
82
- </ul>
83
- </details>
84
-
85
- <h2></h2>
42
+ <details>
43
+ <summary><strong><code>className</code></strong>: <em>Additional classes for the component.</em></summary><br />
44
+ <ul>
45
+ <strong>Type:</strong> string<br />
46
+ <br />
47
+ <strong>Description:</strong> <em><br />
48
+ This parameter allows you to apply custom CSS classes to the <code>MorphScroll</code> component, enabling further customization and styling to fit your design needs.</em><br />
49
+ <br />
50
+ <strong>Example:</strong>
51
+
52
+ ```tsx
53
+ <MorphScroll
54
+ className="your-class"
55
+ // another props
56
+ >
57
+ {children}
58
+ </MorphScroll>
59
+ ```
60
+
61
+ </ul></details>
62
+
63
+ <h2></h2>
64
+
65
+ <details>
66
+ <summary><strong><code>children</code></strong>: <em>Custom user content.</em></summary><br />
67
+ <ul>
68
+ <strong>Type:</strong> React.ReactNode<br />
69
+ <br />
70
+ <strong>Description:</strong> <em><br />
71
+ This is where you can pass your list elements.<br />
72
+ Make sure to provide unique keys for each list item, as per React's rules. The <code>MorphScroll</code> component ensures that the cells it generates will use the same keys as your list items, allowing it to render the correct cells for the current list.<br />
73
+ Additionally, <code>MorphScroll</code> handles a passed <code>null</code> value the same way as <code>undefined</code>, rendering nothing in both cases.</em><br />
74
+ <br />
75
+ <strong>Example:</strong>
76
+
77
+ ```tsx
78
+ <MorphScroll
79
+ // props
80
+ >
81
+ {children}
82
+ </MorphScroll>
83
+ ```
84
+
85
+ </ul></details>
86
+
87
+ <h2></h2>
86
88
 
87
89
  #### SCROLL SETTINGS:
88
90
 
89
- <details>
90
- <summary><strong><code>type</code></strong>: <em>Type of progress element.</em></summary><br />
91
- <ul>
92
- <strong>Type:</strong> "scroll" | "slider"<br />
93
- <br />
94
- <strong>Default:</strong> "scroll"<br />
95
- <br />
96
- <strong>Description:</strong> <em><br />
97
- This parameter defines how the provided <code>progressElement</code> behaves within <code>progressTrigger</code> and how you interact with it.<br />
98
- With the default <code>type="scroll"</code>, it functions as a typical scrollbar. However, with <code>type="slider"</code>, it displays distinct elements indicating the number of full scroll steps within the list.<br />
99
- For More details, refer to <code>progressTrigger/progressElement</code>.</em><br />
100
- <br />
101
- <strong>Example:</strong>
102
-
103
- ```tsx
104
- <MorphScroll
105
- type="slider"
106
- // another props
107
- >
108
- {children}
109
- </MorphScroll>
110
- ```
111
-
112
- </ul>
113
- </details>
114
-
115
- <h2></h2>
116
-
117
- <details>
118
- <summary><strong><code>direction</code></strong>: <em>Scrolling direction.</em></summary><br />
119
- <ul>
120
- <strong>Type:</strong> "x" | "y"<br />
121
- <br />
122
- <strong>Default:</strong> "y"<br />
123
- <br />
124
- <strong>Description:</strong> <em><br />
125
- This parameter changes the scroll or slider type direction based on the provided value.<br />
126
- You can set it to horizontal or vertical to customize the component according to your needs.</em><br />
127
- <br />
128
- <strong>Example:</strong>
129
-
130
- ```tsx
131
- <MorphScroll
132
- direction="x"
133
- // another props
134
- >
135
- {children}
136
- </MorphScroll>
137
- ```
138
-
139
- </ul>
140
- </details>
141
-
142
- <h2></h2>
143
-
144
- <details>
145
- <summary><strong><code>scrollTop</code></strong>: <em>Scroll position and animation duration.</em></summary><br />
146
- <ul>
147
- <strong>Type:</strong> {<br />
148
- value: number | "end";<br />
149
- duration?: number;<br />
150
- updater?: boolean;<br />
151
- }<br />
152
- <br />
153
- <strong>Default:</strong> { value: 0; duration: 200; updater: false }<br />
154
- <br />
155
- <strong>Description:</strong> <em><br />
156
- This parameter allows you to set custom scroll values.<br />
157
- <br />
158
- The <code>value</code> property accepts numerical pixel values.<br />
159
- The <code>"end"</code> option scrolls to the bottom of the list upon loading, which is useful for scenarios like chat message lists. When new elements are appended to the list, the scroll position will update automatically. However, to prevent unwanted scrolling when adding elements to the beginning of the list, this property will not trigger.<br />
160
- <br />
161
- The <code>duration</code> property determines the animation speed for scrolling in ms.</em><br />
162
- <br />
163
- The <code>updater</code> property is a helper for the <code>value</code> property. When setting the same scroll value repeatedly (e.g., clicking a button to scroll to the top), React does not register the update. To force an update, toggle updater within setState, e.g.,<br />
164
- <code>setScroll((prev) => ({ ...prev, value: 0, updater: !prev.updater }))</code></em><br />
165
- <br />
166
- <strong>Example:</strong>
167
-
168
- ```tsx
169
- <MorphScroll
170
- scrollTop={{ value: 100; duration: 100 }}
171
- // another props
172
- >
173
- {children}
174
- </MorphScroll>
175
- ```
176
-
177
- </ul>
178
- </details>
179
-
180
- <h2></h2>
181
-
182
- <details>
183
- <summary><strong><code>stopLoadOnScroll</code></strong>: <em>Stop loading when scrolling.</em></summary><br />
184
- <ul>
185
- <strong>Type:</strong> boolean<br />
186
- <br />
187
- <strong>Default:</strong> false<br />
188
- <br />
189
- <strong>Description:</strong> <em><br />
190
- This parameter helps optimize list performance during scrolling. When set to <code>true</code>, new items will not load while the list is being scrolled and will only load after scrolling stops. This can be particularly useful for lists with a large number of items.</em><br />
191
- <br />
192
- <strong>Example:</strong>
193
-
194
- ```tsx
195
- <MorphScroll
196
- stopLoadOnScroll
197
- // another props
198
- >
199
- {children}
200
- </MorphScroll>
201
- ```
202
-
203
- </ul>
204
- </details>
205
-
206
- <h2></h2>
207
-
208
- <details>
209
- <summary><strong><code>onScrollValue</code></strong>: <em>Callback for scroll value.</em></summary><br />
210
- <ul>
211
- <strong>Type:</strong> (scroll: number) => void<br />
212
- <br />
213
- <strong>Description:</strong> <em><br />
214
- This parameter accepts a callback function that is triggered on every scroll event. The callback receives the current scroll position as a number. The return value of the callback can be used to determine custom behavior based on the scroll value.</em><br />
215
- <br />
216
- <strong>Example:</strong>
217
-
218
- ```tsx
219
- <MorphScroll
220
- onScrollValue={
221
- (scroll) => {
222
- console.log("Scroll position:", scroll);
223
- return scroll > 100;
224
- },
225
- }
226
- // another props
227
- >
228
- {children}
229
- </MorphScroll>
230
- ```
231
-
232
- </ul>
233
- </details>
234
-
235
- <h2></h2>
236
-
237
- <details>
238
- <summary><strong><code>isScrolling</code></strong>: <em>Callback function for scroll status.</em></summary><br />
239
- <ul>
240
- <strong>Type:</strong> (motion: boolean) => void<br />
241
- <br />
242
- <strong>Description:</strong> <em><br />
243
- This parameter accepts a callback function that is triggered whenever the scroll status changes. The callback receives a boolean value, where <code>true</code> indicates that scrolling is in progress, and <code>false</code> indicates that scrolling has stopped. This can be useful for triggering additional actions, such as pausing animations or loading indicators based on the scroll state.</em><br />
244
- <br />
245
- <strong>Example:</strong>
246
-
247
- ```tsx
248
- <MorphScroll
249
- isScrolling={(motion) => {
250
- console.log(motion ? "Scrolling..." : "Scroll stopped.");
251
- }}
252
- // another props
253
- >
254
- {children}
255
- </MorphScroll>
256
- ```
257
-
258
- </ul>
259
- </details>
260
-
261
- <h2></h2>
91
+ <details>
92
+ <summary><strong><code>type</code></strong>: <em>Type of progress element.</em></summary><br />
93
+ <ul>
94
+ <strong>Type:</strong> "scroll" | "slider"<br />
95
+ <br />
96
+ <strong>Default:</strong> "scroll"<br />
97
+ <br />
98
+ <strong>Description:</strong> <em><br />
99
+ This parameter defines how the provided <code>progressElement</code> behaves within <code>progressTrigger</code> and how you interact with it.<br />
100
+ With the default <code>type="scroll"</code>, it functions as a typical scrollbar. However, with <code>type="slider"</code>, it displays distinct elements indicating the number of full scroll steps within the list.<br />
101
+ For More details, refer to <code>progressTrigger/progressElement</code>.</em><br />
102
+ <br />
103
+ <strong>Example:</strong>
104
+
105
+ ```tsx
106
+ <MorphScroll
107
+ type="slider"
108
+ // another props
109
+ >
110
+ {children}
111
+ </MorphScroll>
112
+ ```
113
+
114
+ </ul></details>
115
+
116
+ <h2></h2>
117
+
118
+ <details>
119
+ <summary><strong><code>direction</code></strong>: <em>Scrolling direction.</em></summary><br />
120
+ <ul>
121
+ <strong>Type:</strong> "x" | "y"<br />
122
+ <br />
123
+ <strong>Default:</strong> "y"<br />
124
+ <br />
125
+ <strong>Description:</strong> <em><br />
126
+ This parameter changes the scroll or slider type direction based on the provided value.<br />
127
+ You can set it to horizontal or vertical to customize the component according to your needs.</em><br />
128
+ <br />
129
+ <strong>Example:</strong>
130
+
131
+ ```tsx
132
+ <MorphScroll
133
+ direction="x"
134
+ // another props
135
+ >
136
+ {children}
137
+ </MorphScroll>
138
+ ```
139
+
140
+ </ul></details>
141
+
142
+ <h2></h2>
143
+
144
+ <details>
145
+ <summary><strong><code>scrollTop</code></strong>: <em>Scroll position and animation duration.</em></summary><br />
146
+ <ul>
147
+ <strong>Type:</strong> {<br />
148
+ value: number | "end";<br />
149
+ duration?: number;<br />
150
+ updater?: boolean;<br />
151
+ }<br />
152
+ <br />
153
+ <strong>Default:</strong> { value: 0; duration: 200; updater: false }<br />
154
+ <br />
155
+ <strong>Description:</strong> <em><br />
156
+ This parameter allows you to set custom scroll values.<br />
157
+ <br />
158
+ The <code>value</code> property accepts numerical pixel values.<br />
159
+ The <code>"end"</code> option scrolls to the bottom of the list upon loading, which is useful for scenarios like chat message lists. When new elements are appended to the list, the scroll position will update automatically. However, to prevent unwanted scrolling when adding elements to the beginning of the list, this property will not trigger.<br />
160
+ <br />
161
+ The <code>duration</code> property determines the animation speed for scrolling in ms.</em><br />
162
+ <br />
163
+ The <code>updater</code> property is a helper for the <code>value</code> property. When setting the same scroll value repeatedly (e.g., clicking a button to scroll to the top), React does not register the update. To force an update, toggle updater within setState, e.g.,<br />
164
+ <code>setScroll((prev) => ({ ...prev, value: 0, updater: !prev.updater }))</code></em><br />
165
+ <br />
166
+ <strong>Example:</strong>
167
+
168
+ ```tsx
169
+ <MorphScroll
170
+ scrollTop={{ value: 100; duration: 100 }}
171
+ // another props
172
+ >
173
+ {children}
174
+ </MorphScroll>
175
+ ```
176
+
177
+ </ul></details>
178
+
179
+ <h2></h2>
180
+
181
+ <details>
182
+ <summary><strong><code>stopLoadOnScroll</code></strong>: <em>Stop loading when scrolling.</em></summary><br />
183
+ <ul>
184
+ <strong>Type:</strong> boolean<br />
185
+ <br />
186
+ <strong>Default:</strong> false<br />
187
+ <br />
188
+ <strong>Description:</strong> <em><br />
189
+ This parameter helps optimize list performance during scrolling. When set to <code>true</code>, new items will not load while the list is being scrolled and will only load after scrolling stops. This can be particularly useful for lists with a large number of items.</em><br />
190
+ <br />
191
+ <strong>Example:</strong>
192
+
193
+ ```tsx
194
+ <MorphScroll
195
+ stopLoadOnScroll
196
+ // another props
197
+ >
198
+ {children}
199
+ </MorphScroll>
200
+ ```
201
+
202
+ </ul></details>
203
+
204
+ <h2></h2>
205
+
206
+ <details>
207
+ <summary><strong><code>onScrollValue</code></strong>: <em>Callback for scroll value.</em></summary><br />
208
+ <ul>
209
+ <strong>Type:</strong> (scroll: number) => void<br />
210
+ <br />
211
+ <strong>Description:</strong> <em><br />
212
+ This parameter accepts a callback function that is triggered on every scroll event. The callback receives the current scroll position as a number. The return value of the callback can be used to determine custom behavior based on the scroll value.</em><br />
213
+ <br />
214
+ <strong>Example:</strong>
215
+
216
+ ```tsx
217
+ <MorphScroll
218
+ onScrollValue={
219
+ (scroll) => {
220
+ console.log("Scroll position:", scroll);
221
+ return scroll > 100;
222
+ },
223
+ }
224
+ // another props
225
+ >
226
+ {children}
227
+ </MorphScroll>
228
+ ```
229
+
230
+ </ul></details>
231
+
232
+ <h2></h2>
233
+
234
+ <details>
235
+ <summary><strong><code>isScrolling</code></strong>: <em>Callback function for scroll status.</em></summary><br />
236
+ <ul>
237
+ <strong>Type:</strong> (motion: boolean) => void<br />
238
+ <br />
239
+ <strong>Description:</strong> <em><br />
240
+ This parameter accepts a callback function that is triggered whenever the scroll status changes. The callback receives a boolean value, where <code>true</code> indicates that scrolling is in progress, and <code>false</code> indicates that scrolling has stopped. This can be useful for triggering additional actions, such as pausing animations or loading indicators based on the scroll state.</em><br />
241
+ <br />
242
+ <strong>Example:</strong>
243
+
244
+ ```tsx
245
+ <MorphScroll
246
+ isScrolling={(motion) => {
247
+ console.log(motion ? "Scrolling..." : "Scroll stopped.");
248
+ }}
249
+ // another props
250
+ >
251
+ {children}
252
+ </MorphScroll>
253
+ ```
254
+
255
+ </ul></details>
256
+
257
+ <h2></h2>
262
258
 
263
259
  #### VISUAL SETTINGS:
264
260
 
265
- <details>
266
- <summary><strong><code>size</code></strong>: <em>MorphScroll width and height.</em></summary><br />
267
- <ul>
268
- <strong>Type:</strong> number[]<br />
269
- <br />
270
- <strong>Description:</strong> <em><br />
271
- This parameter sets the width and height of the <code>MorphScroll</code> component as an array of two numbers. These values help define the visual container for the scrollable area.<br />
272
- <br />
273
- If this parameter is not specified, <code>MorphScroll</code> will use the <code>ResizeTracker</code> component to measure the width and height of the area where <code>MorphScroll</code> is added. The dimensions will automatically adjust when the container changes.<br />
274
- <br />
275
- ⚠ Note:<br />
261
+ <details>
262
+ <summary><strong><code>size</code></strong>: <em>MorphScroll width and height.</em></summary><br />
276
263
  <ul>
277
- <li>The values are specified following the <code>width/height</code> rule in pixels, regardless of the <code>direction</code>.</li>
278
- <li>See the <code>ResizeTracker</code> section for more details.</li>
279
- </ul></em><br />
280
- <br />
281
- <strong>Example:</strong>
282
-
283
- ```tsx
284
- <MorphScroll
285
- size={[100, 400]}
286
- // another props
287
- >
288
- {children}
289
- </MorphScroll>
290
- ```
291
-
292
- </ul>
293
- </details>
294
-
295
- <h2></h2>
296
-
297
- <details>
298
- <summary><strong><code>objectsSize</code> (required)</strong>: <em>Required: Size of cells for each object.</em></summary><br />
299
- <ul>
300
- <strong>Type:</strong> (number | "none" | "firstChild")[]<br />
301
- <br />
302
- <strong>Description:</strong> <em><br />
303
- This parameter is the only required one. It defines the size of cells for each of your objects. <code>ObjectsSize</code> use an array of values.<br />
304
- <br />
305
- If you pass <code>"none"</code>, cells will still be created, but <code>MorphScroll</code> will not calculate their sizes-they will simply wrap your objects. In this case, for example, you won’t be able to use the <code>infiniteScroll</code> feature, as it requires specific cell sizes for absolute positioning.. However, this is not a drawback if you are building something like a chat or a news feed, where the content can have varying heights, and it’s better to load new content as the user approaches the end of the existing list.<br />
306
- <br />
307
- If you specify the value <code>"firstChild"</code>, a <code>ResizeTracker</code> wrapper will be created for the first child of your list. This wrapper will calculate the size of the first child, and these dimensions will be applied to all cells in the list.<br />
308
- <br />
309
- ⚠ Note:<br />
310
- The numbers are specified following the <code>width/height</code> rule, regardless of the <code>direction</code>.</em><br />
311
- <br />
312
- <strong>Example:</strong>
313
-
314
- ```tsx
315
- <MorphScroll
316
- objectsSize={[40, 40]}
317
- // objectsSize={["none", "none"]}
318
- // objectsSize={["firstChild", "firstChild"]}
319
- // another props
320
- >
321
- {children}
322
- </MorphScroll>
323
- ```
324
-
325
- </ul>
326
- </details>
327
-
328
- <h2></h2>
329
-
330
- <details>
331
- <summary><strong><code>gap</code></strong>: <em>Gap between cells.</em></summary><br />
332
- <ul>
333
- <strong>Type:</strong> number[] | number<br />
334
- <br />
335
- <strong>Description:</strong> <em><br />
336
- This parameter allows you to set spacing between list items both horizontally and vertically. You can provide a single value, which will apply to both directions, or an array of two numbers to define separate spacing values.<br />
337
- <br />
338
- ⚠ Note:<br />
339
- The values are specified following the <code>horizontal/vertical</code> rule in pixels, regardless of the <code>direction</code>.</em><br />
340
- <br />
341
- <strong>Example:</strong>
342
-
343
- ```tsx
344
- <MorphScroll
345
- gap={10}
346
- // gap={[10, 10]}
347
- // another props
348
- >
349
- {children}
350
- </MorphScroll>
351
- ```
352
-
353
- </ul>
354
- </details>
355
-
356
- <h2></h2>
357
-
358
- <details>
359
- <summary><strong><code>padding</code></strong>: <em>Padding for the <code>objectsWrapper</code>.</em></summary><br />
360
- <ul>
361
- <strong>Type:</strong> number[] | number<br />
362
- <br />
363
- <strong>Description:</strong> <em><br />
364
- This parameter defines the spacing between the list items and their wrapper, effectively increasing the width or height of the scrollable area. You can provide a single number, which will apply to all sides, or an array of two or four numbers to specify spacing for specific directions.<br />
365
- <br />
366
- ⚠ Note:<br />
264
+ <strong>Type:</strong> number[]<br />
265
+ <br />
266
+ <strong>Description:</strong> <em><br />
267
+ This parameter sets the width and height of the <code>MorphScroll</code> component as an array of two numbers. These values help define the visual container for the scrollable area.<br />
268
+ <br />
269
+ If this parameter is not specified, <code>MorphScroll</code> will use the <code>ResizeTracker</code> component to measure the width and height of the area where <code>MorphScroll</code> is added. The dimensions will automatically adjust when the container changes.<br />
270
+ <br />
271
+ ⚠ Note:<br />
272
+ <ul>
273
+ <li>The values are specified following the <code>width/height</code> rule in pixels, regardless of the <code>direction</code>.</li>
274
+ <li>See the <code>ResizeTracker</code> section for more details.</li>
275
+ </ul></em><br />
276
+ <br />
277
+ <strong>Example:</strong>
278
+
279
+ ```tsx
280
+ <MorphScroll
281
+ size={[100, 400]}
282
+ // another props
283
+ >
284
+ {children}
285
+ </MorphScroll>
286
+ ```
287
+
288
+ </ul></details>
289
+
290
+ <h2></h2>
291
+
292
+ <details>
293
+ <summary><strong><code>objectsSize</code> (required)</strong>: <em>Required: Size of cells for each object.</em></summary><br />
367
294
  <ul>
368
- <li>
369
- This parameter accepts either a single number or an array of numbers
370
- <ul>
371
- <li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
372
- <li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
373
- </ul>
374
- </li>
375
- <li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
376
- <li>This is not a CSS property, even though its name might suggest otherwise. It specifically refers to modifying the width and height of the scrollable wrapper, affecting the dimensions of the scrollable area.</li>
377
- </ul></em><br />
378
- <br />
379
- <strong>Example:</strong>
380
-
381
- ```tsx
382
- <MorphScroll
383
- padding={10}
384
- // padding={[10, 10]}
385
- // padding={[10, 10, 10, 10]}
386
- // another props
387
- >
388
- {children}
389
- </MorphScroll>
390
- ```
391
-
392
- </ul>
393
- </details>
394
-
395
- <h2></h2>
396
-
397
- <details>
398
- <summary><strong><code>contentAlign</code></strong>: <em>Aligns the content when it is smaller than the MorphScroll <code>size</code>.</em></summary><br />
399
- <ul>
400
- <strong>Type:</strong> [<br />
401
- "start" | "center" | "end",<br />
402
- "start" | "center" | "end"<br />
403
- ]<br />
404
- <strong>Description:</strong> <em><br />
405
- This parameter aligns the `objectsWrapper`, which contains all the provided elements, relative to the scroll or the `size`.<br />
406
- <br />
407
- ⚠ Note:<br />
295
+ <strong>Type:</strong> (number | "none" | "firstChild")[]<br />
296
+ <br />
297
+ <strong>Description:</strong> <em><br />
298
+ This parameter is the only required one. It defines the size of cells for each of your objects. <code>ObjectsSize</code> use an array of values.<br />
299
+ <br />
300
+ If you pass <code>"none"</code>, cells will still be created, but <code>MorphScroll</code> will not calculate their sizes-they will simply wrap your objects. In this case, for example, you won’t be able to use the <code>infiniteScroll</code> feature, as it requires specific cell sizes for absolute positioning.. However, this is not a drawback if you are building something like a chat or a news feed, where the content can have varying heights, and it’s better to load new content as the user approaches the end of the existing list.<br />
301
+ <br />
302
+ If you specify the value <code>"firstChild"</code>, a <code>ResizeTracker</code> wrapper will be created for the first child of your list. This wrapper will calculate the size of the first child, and these dimensions will be applied to all cells in the list.<br />
303
+ <br />
304
+ ⚠ Note:<br />
305
+ The numbers are specified following the <code>width/height</code> rule, regardless of the <code>direction</code>.</em><br />
306
+ <br />
307
+ <strong>Example:</strong>
308
+
309
+ ```tsx
310
+ <MorphScroll
311
+ objectsSize={[40, 40]}
312
+ // objectsSize={["none", "none"]}
313
+ // objectsSize={["firstChild", "firstChild"]}
314
+ // another props
315
+ >
316
+ {children}
317
+ </MorphScroll>
318
+ ```
319
+
320
+ </ul></details>
321
+
322
+ <h2></h2>
323
+
324
+ <details>
325
+ <summary><strong><code>gap</code></strong>: <em>Gap between cells.</em></summary><br />
408
326
  <ul>
409
- <li>Only takes effect when `objectsWrapper` is smaller than the scroll container.
410
- </li>
411
- <li>The values are specified following the horizontal/vertical rule, regardless of the direction.
412
- </li>
413
- </ul></em><br />
414
- <br />
415
- <strong>Example:</strong>
416
-
417
- ```tsx
418
- <MorphScroll
419
- contentAlign={["center", "center"]}
420
- // another props
421
- >
422
- {children}
423
- </MorphScroll>
424
- ```
425
-
426
- </ul>
427
- </details>
428
-
429
- <h2></h2>
430
-
431
- <details>
432
- <summary><strong><code>elementsAlign</code></strong>: <em>Aligns the objects within the <code>objectsWrapper</code>.</em></summary><br />
433
- <ul>
434
- <strong>Type:</strong> "start" | "center" | "end"<br />
435
- <br />
436
- <strong>Example:</strong>
437
-
438
- ```tsx
439
- <MorphScroll
440
- elementsAlign="center"
441
- // another props
442
- >
443
- {children}
444
- </MorphScroll>
445
- ```
446
-
447
- </ul>
448
- </details>
449
-
450
- <h2></h2>
451
-
452
- <details>
453
- <summary><strong><code>edgeGradient</code></strong>: <em>Gradient when scrolling overflows.</em></summary><br />
454
- <ul>
455
- <strong>Type:</strong> boolean | { color?: string; size?: number }<br />
456
- <br />
457
- <strong>Default:</strong> When using true or color, the default size will be 40<br />
458
- <br />
459
- <strong>Description:</strong> <em><br />
460
- This parameter creates two edge elements responsible for darkening the edges of the scroll when it overflows.<br />
461
- <br />
462
- The color property accepts any valid color format. If specified, the library will generate a gradient transitioning from the custom color to transparent. If omitted, the edge elements will have no color, allowing for custom styling via CSS classes.<br />
463
- <br />
464
- ⚠ Note:<br />
465
- The size property, measured in pixels, adjusts the dimensions of the edge elements.</em><br />
466
- <br />
467
- <strong>Example:</strong>
468
-
469
- ```tsx
470
- <MorphScroll
471
- edgeGradient={{ color: "rgba(0, 0, 0, 0.5)" }}
472
- // edgeGradient={{ color: "rgba(0, 0, 0, 0.5)", size: 20 }}
473
- // edgeGradient
474
- // another props
475
- >
476
- {children}
477
- </MorphScroll>
478
- ```
479
-
480
- </ul>
481
- </details>
482
-
483
- <h2></h2>
484
-
485
- <details>
486
- <summary><strong><code>progressReverse</code></strong>: <em>Reverse the progress bar position.</em></summary><br />
487
- <ul>
488
- <strong>Type:</strong> boolean<br />
489
- <br />
490
- <strong>Default:</strong> false<br />
491
- <br />
492
- <strong>Description:</strong> <em><br />
493
- This parameter changes the position of the progress bar based on the direction property.<br />
327
+ <strong>Type:</strong> number[] | number<br />
328
+ <br />
329
+ <strong>Description:</strong> <em><br />
330
+ This parameter allows you to set spacing between list items both horizontally and vertically. You can provide a single value, which will apply to both directions, or an array of two numbers to define separate spacing values.<br />
331
+ <br />
332
+ ⚠ Note:<br />
333
+ The values are specified following the <code>horizontal/vertical</code> rule in pixels, regardless of the <code>direction</code>.</em><br />
334
+ <br />
335
+ <strong>Example:</strong>
336
+
337
+ ```tsx
338
+ <MorphScroll
339
+ gap={10}
340
+ // gap={[10, 10]}
341
+ // another props
342
+ >
343
+ {children}
344
+ </MorphScroll>
345
+ ```
346
+
347
+ </ul></details>
348
+
349
+ <h2></h2>
350
+
351
+ <details>
352
+ <summary><strong><code>padding</code></strong>: <em>Padding for the <code>objectsWrapper</code>.</em></summary><br />
494
353
  <ul>
495
- <li>If <code>direction="x"</code>, the progress bar is on the left by default and moves to the right when <code>progressReverse</code> is enabled.</li>
496
- <li>If <code>direction="y"</code>, the progress bar is at the top by default and moves to the bottom when <code>progressReverse</code> is enabled.</li>
497
- </ul></em><br />
498
- <br />
499
- <strong>Example:</strong>
500
-
501
- ```tsx
502
- <MorphScroll
503
- progressReverse
504
- // another props
505
- >
506
- {children}
507
- </MorphScroll>
508
- ```
509
-
510
- </ul>
511
- </details>
512
-
513
- <h2></h2>
514
-
515
- <details>
516
- <summary><strong><code>progressVisibility</code></strong>: <em>Visibility of the progress bar.</em></summary><br />
517
- <ul>
518
- <strong>Type:</strong> "visible" | "hover" | "hidden"<br />
519
- <br />
520
- <strong>Default:</strong> "visible"<br />
521
- <br />
522
- <strong>Description:</strong> <em><br />
523
- This parameter controls the visibility of the progress bar regardless of the <code>type</code> value.</em><br />
524
- <br />
525
- <strong>Example:</strong>
526
-
527
- ```tsx
528
- <MorphScroll
529
- progressVisibility="hover"
530
- // another props
531
- >
532
- {children}
533
- </MorphScroll>
534
- ```
535
-
536
- </ul>
537
- </details>
538
-
539
- <h2></h2>
540
-
541
- <details>
542
- <summary><strong><code>objectsWrapFullMinSize</code></strong>: <em>Sets the <code>min-height</code> CSS property of the <code>objectsWrapper</code> to match the height of the MorphScroll.</em></summary><br />
543
- <ul>
544
- <strong>Type:</strong> boolean<br /><br />
545
- <strong>Default:</strong> false<br /><br />
546
- <strong>Description:</strong> <em><br />
547
- In process of development</em><br />
548
- <br />
549
- <strong>Example:</strong>
550
-
551
- ```tsx
552
- <MorphScroll
553
- objectsWrapFullMinSize
554
- // another props
555
- >
556
- {children}
557
- </MorphScroll>
558
- ```
354
+ <strong>Type:</strong> number[] | number<br />
355
+ <br />
356
+ <strong>Description:</strong> <em><br />
357
+ This parameter defines the spacing between the list items and their wrapper, effectively increasing the width or height of the scrollable area. You can provide a single number, which will apply to all sides, or an array of two or four numbers to specify spacing for specific directions.<br />
358
+ <br />
359
+ ⚠ Note:<br />
360
+ <ul>
361
+ <li>
362
+ This parameter accepts either a single number or an array of numbers
363
+ <ul>
364
+ <li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
365
+ <li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
366
+ </ul>
367
+ </li>
368
+ <li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
369
+ <li>This is not a CSS property, even though its name might suggest otherwise. It specifically refers to modifying the width and height of the scrollable wrapper, affecting the dimensions of the scrollable area.</li>
370
+ </ul></em><br />
371
+ <br />
372
+ <strong>Example:</strong>
373
+
374
+ ```tsx
375
+ <MorphScroll
376
+ padding={10}
377
+ // padding={[10, 10]}
378
+ // padding={[10, 10, 10, 10]}
379
+ // another props
380
+ >
381
+ {children}
382
+ </MorphScroll>
383
+ ```
384
+
385
+ </ul></details>
386
+
387
+ <h2></h2>
388
+
389
+ <details>
390
+ <summary><strong><code>contentAlign</code></strong>: <em>Aligns the content when it is smaller than the MorphScroll <code>size</code>.</em></summary><br />
391
+ <ul>
392
+ <strong>Type:</strong> [<br />
393
+ "start" | "center" | "end",<br />
394
+ "start" | "center" | "end"<br />
395
+ ]<br />
396
+ <strong>Description:</strong> <em><br />
397
+ This parameter aligns the `objectsWrapper`, which contains all the provided elements, relative to the scroll or the `size`.<br />
398
+ <br />
399
+ ⚠ Note:<br />
400
+ <ul>
401
+ <li>Only takes effect when `objectsWrapper` is smaller than the scroll container.
402
+ </li>
403
+ <li>The values are specified following the horizontal/vertical rule, regardless of the direction.
404
+ </li>
405
+ </ul></em><br />
406
+ <br />
407
+ <strong>Example:</strong>
408
+
409
+ ```tsx
410
+ <MorphScroll
411
+ contentAlign={["center", "center"]}
412
+ // another props
413
+ >
414
+ {children}
415
+ </MorphScroll>
416
+ ```
417
+
418
+ </ul></details>
419
+
420
+ <h2></h2>
421
+
422
+ <details>
423
+ <summary><strong><code>elementsAlign</code></strong>: <em>Aligns the objects within the <code>objectsWrapper</code>.</em></summary><br />
424
+ <ul>
425
+ <strong>Type:</strong> "start" | "center" | "end"<br />
426
+ <br />
427
+ <strong>Example:</strong>
559
428
 
560
- </ul>
561
- </details>
429
+ ```tsx
430
+ <MorphScroll
431
+ elementsAlign="center"
432
+ // another props
433
+ >
434
+ {children}
435
+ </MorphScroll>
436
+ ```
562
437
 
563
- <h2></h2>
438
+ </ul></details>
564
439
 
565
- #### PROGRESS AND RENDERING:
440
+ <h2></h2>
566
441
 
567
- <details>
568
- <summary><strong><code>progressTrigger</code></strong>: <em>Triggers for the progress bar.</em></summary><br />
569
- <ul>
570
- <strong>Type:</strong> {<br />
571
- wheel?: boolean;<br />
572
- content?: boolean;<br />
573
- progressElement?: boolean | React.ReactNode;<br />
574
- arrows?: boolean | { size?: number; element?: React.ReactNode };<br />
575
- }<br />
576
- <br />
577
- <strong>Default:</strong> { wheel: true }<br />
578
- <br />
579
- <strong>Description:</strong> <em><br />
580
- This is one of the most important parameters, allowing you to define how users interact with the progress bar and customize its appearance.<br />
581
- <br />
442
+ <details>
443
+ <summary><strong><code>edgeGradient</code></strong>: <em>Gradient when scrolling overflows.</em></summary><br />
582
444
  <ul>
583
- <li>The <code>wheel</code> property determines whether the progress bar responds to mouse wheel scrolling.</li>
584
- <li>The <code>content</code> property enables interaction by clicking and dragging anywhere within the scrollable content to move it.</li>
585
- <li>The <code>progressElement</code> property defines whether the progress bar is controlled by a custom element. If your custom scroll element is not ready yet, you can simply pass <code>true</code>, which will display the browser's default scrollbar when <code>type="scroll"</code> is used. Alternatively, if <code>type="slider"</code> is set, a <code>sliderBar</code> element will be created, containing multiple <code>sliderElem</code> elements representing progress. Depending on the position, one of these elements will always have the <code>active</code> class.</li>
586
- <li>The <code>arrows</code> property allows you to add custom arrows to the progress bar. You can either specify a <code>size</code> for the arrows and provide a custom <code>element</code>.</li>
587
- </ul></em><br />
588
- <br />
589
- <strong>Example:</strong>
590
-
591
- ```tsx
592
- <MorphScroll
593
- progressTrigger={{
594
- wheel: true,
595
- progressElement: <div className="your-scroll-thumb" />,
596
- }}
597
- // another props
598
- >
599
- {children}
600
- </MorphScroll>
601
- ```
602
-
603
- </ul>
604
- </details>
605
-
606
- <h2></h2>
607
-
608
- <details>
609
- <summary><strong><code>render</code></strong>: <em>Types of rendering for optimization.</em></summary><br />
610
- <ul>
611
- <strong>Type:</strong><br />
612
- | { type: "default" }<br />
613
- | { type: "lazy"; rootMargin?: number | number[]; onVisible?: (key: string) => void }<br />
614
- | { type: "virtual"; rootMargin?: number | number[] }<br />
615
- <br />
616
- <strong>Default:</strong> { type: "default" }<br />
617
- <br />
618
- <strong>Description:</strong> <em><br />
619
- This parameter defines the rendering type for optimization.<br />
620
- <br />
445
+ <strong>Type:</strong> boolean | { color?: string; size?: number }<br />
446
+ <br />
447
+ <strong>Default:</strong> When using true or color, the default size will be 40<br />
448
+ <br />
449
+ <strong>Description:</strong> <em><br />
450
+ This parameter creates two edge elements responsible for darkening the edges of the scroll when it overflows.<br />
451
+ <br />
452
+ The color property accepts any valid color format. If specified, the library will generate a gradient transitioning from the custom color to transparent. If omitted, the edge elements will have no color, allowing for custom styling via CSS classes.<br />
453
+ <br />
454
+ ⚠ Note:<br />
455
+ The size property, measured in pixels, adjusts the dimensions of the edge elements.</em><br />
456
+ <br />
457
+ <strong>Example:</strong>
458
+
459
+ ```tsx
460
+ <MorphScroll
461
+ edgeGradient={{ color: "rgba(0, 0, 0, 0.5)" }}
462
+ // edgeGradient={{ color: "rgba(0, 0, 0, 0.5)", size: 20 }}
463
+ // edgeGradient
464
+ // another props
465
+ >
466
+ {children}
467
+ </MorphScroll>
468
+ ```
469
+
470
+ </ul></details>
471
+
472
+ <h2></h2>
473
+
474
+ <details>
475
+ <summary><strong><code>progressReverse</code></strong>: <em>Reverse the progress bar position.</em></summary><br />
621
476
  <ul>
622
- <li>With <code>default</code>, no optimizations are applied.</li>
623
- <li>With <code>lazy</code>, containers are created but do not load content until they enter the viewport. The <code>rootMargin</code> property controls the threshold for loading, and the <code>onVisible</code> callback function can be used to trigger actions when a container becomes visible for each scrollable object and provides the key of the first element in the container.</li>
624
- <li>With <code>virtual</code>, a container is created for each scrollable object, and its absolute positioning is calculated based on <code>scrollTop</code> and scroll area dimensions. Rendering is dynamically adjusted according to the scroll position. The <code>rootMargin</code> property can also be used to extend the rendering area.</li>
625
- </ul><br />
626
- <br />
627
- ⚠ Note:<br />
477
+ <strong>Type:</strong> boolean<br />
478
+ <br />
479
+ <strong>Default:</strong> false<br />
480
+ <br />
481
+ <strong>Description:</strong> <em><br />
482
+ This parameter changes the position of the progress bar based on the direction property.<br />
483
+ <ul>
484
+ <li>If <code>direction="x"</code>, the progress bar is on the left by default and moves to the right when <code>progressReverse</code> is enabled.</li>
485
+ <li>If <code>direction="y"</code>, the progress bar is at the top by default and moves to the bottom when <code>progressReverse</code> is enabled.</li>
486
+ </ul></em><br />
487
+ <br />
488
+ <strong>Example:</strong>
489
+
490
+ ```tsx
491
+ <MorphScroll
492
+ progressReverse
493
+ // another props
494
+ >
495
+ {children}
496
+ </MorphScroll>
497
+ ```
498
+
499
+ </ul></details>
500
+
501
+ <h2></h2>
502
+
503
+ <details>
504
+ <summary><strong><code>progressVisibility</code></strong>: <em>Visibility of the progress bar.</em></summary><br />
628
505
  <ul>
629
- <li>The <code>onVisible</code> property is the same as in <code>IntersectionTracker/onVisible</code>.</li>
630
- <li>
631
- The <code>rootMargin</code> property accepts either a single number or an array of numbers.
632
- <ul>
633
- <li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
634
- <li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
635
- </ul>
636
- </li>
637
- <li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
638
- </ul></em><br />
639
- <br />
640
- <strong>Example:</strong>
641
-
642
- ```tsx
643
- <MorphScroll
644
- render={{ type: "virtual" }}
645
- // render={{
646
- // type: "lazy",
647
- // rootMargin: [0, 100],
648
- // onVisible: () => console.log("visible"))
649
- // }}
650
- // another props
651
- >
652
- {children}
653
- </MorphScroll>
654
- ```
655
-
656
- </ul>
657
- </details>
658
-
659
- <h2></h2>
660
-
661
- <details>
662
- <summary><strong><code>emptyElements</code></strong>: <em>Handling of empty scroll elements.</em></summary><br />
663
- <ul>
664
- <strong>Type:</strong><br />
665
- | {
666
- mode: "clear";
667
- clickTrigger?: { selector: string; delay?: number };
668
- }<br />
669
- | {
670
- mode: "fallback";
671
- element?: React.ReactNode;
672
- clickTrigger?: { selector: string; delay?: number };
673
- }<br /><br />
674
- <strong>Description:</strong> <em><br />
675
- If certain components might return nothing during rendering, this parameter helps manage them. The check and subsequent replacement with a fallback element or removal occur after the scroll elements are rendered. Due to this, when dynamically displaying elements in different <code>render</code> modes, you may notice slight position shifts during fast scrolling, as empty elements are removed, causing subsequent elements to reposition.<br />
676
- <br />
506
+ <strong>Type:</strong> "visible" | "hover" | "hidden"<br />
507
+ <br />
508
+ <strong>Default:</strong> "visible"<br />
509
+ <br />
510
+ <strong>Description:</strong> <em><br />
511
+ This parameter controls the visibility of the progress bar regardless of the <code>type</code> value.</em><br />
512
+ <br />
513
+ <strong>Example:</strong>
514
+
515
+ ```tsx
516
+ <MorphScroll
517
+ progressVisibility="hover"
518
+ // another props
519
+ >
520
+ {children}
521
+ </MorphScroll>
522
+ ```
523
+
524
+ </ul></details>
525
+
526
+ <h2></h2>
527
+
528
+ <details>
529
+ <summary><strong><code>objectsWrapFullMinSize</code></strong>: <em>Sets the <code>min-height</code> CSS property of the <code>objectsWrapper</code> to match the height of the MorphScroll.</em></summary><br />
677
530
  <ul>
678
- <li><code>mode: "clear"</code> – automatically removes empty elements, eliminating unnecessary gaps in the scroll list.</li>
679
- <li><code>mode: "fallback"</code> – replaces empty elements with a specified fallback component. By default, it uses the <code>fallback</code> props value, but you can also pass a separate placeholder to <code>element</code>.</li>
680
- </ul><br />
681
- <br />
682
- <code>clickTrigger</code> – if elements are removed via a click action, this property ensures cleanup is triggered accordingly. It accepts an object with a <code>selector</code> (such as a delete button’s class) and an optional <code>delay</code> (a delay in milliseconds to accommodate animations or complex removals).<br />
683
- <br />
684
- ⚠ Note:<br />
685
- For clarification, the cleanup will occur on the initial render, when the number of passed elements changes, on scroll, and on click if you use <code>clickTrigger</code>.</em><br />
686
- <br />
687
- <strong>Example:</strong>
688
-
689
- ```tsx
690
- <MorphScroll
691
- emptyElements={{
692
- mode: "clear",
693
- clickTrigger: { selector: ".close-button" },
694
- }}
695
- // emptyElements={{
696
- // mode: "fallback",
697
- // clickTrigger: {
698
- // selector: ".close-button",
699
- // delay: 100,
700
- // },
701
- // }}
702
- // another props
703
- >
704
- {children}
705
- </MorphScroll>
706
- ```
707
-
708
- </ul>
709
- </details>
710
-
711
- <h2></h2>
712
-
713
- <details>
714
- <summary><strong><code>suspending</code></strong>: <em>Adds React Suspense.</em></summary><br />
715
- <ul>
716
- <strong>Type:</strong> boolean<br />
717
- <br />
718
- <strong>Default:</strong> false<br />
719
- <br />
720
- <strong>Description:</strong> <em><br />
721
- This parameter adds React Suspense to the MorphScroll component for asynchronous rendering.</em><br />
722
- <br />
723
- <strong>Example:</strong>
724
-
725
- ```tsx
726
- <MorphScroll
727
- suspending
728
- // another props
729
- >
730
- {children}
731
- </MorphScroll>
732
- ```
733
-
734
- </ul>
735
- </details>
736
-
737
- <h2></h2>
738
-
739
- <details>
740
- <summary><strong><code>fallback</code></strong>: <em>Fallback element.</em></summary><br />
741
- <ul>
742
- <strong>Type:</strong> React.ReactNode<br />
743
- <br />
744
- <strong>Description:</strong> <em><br />
745
- This parameter sets the fallback element for custom element. It will be used for <code>emptyElements</code> in <code>mode: "fallback"</code> or when <code>suspending</code> is enabled.</em><br />
746
- <br />
747
- <strong>Example:</strong>
748
-
749
- ```tsx
750
- <MorphScroll
751
- fallback={<div>Loading...</div>}
752
- // another props
753
- >
754
- {children}
755
- </MorphScroll>
756
- ```
531
+ <strong>Type:</strong> boolean<br /><br />
532
+ <strong>Default:</strong> false<br /><br />
533
+ <strong>Description:</strong> <em><br />
534
+ In process of development</em><br />
535
+ <br />
536
+ <strong>Example:</strong>
537
+
538
+ ```tsx
539
+ <MorphScroll
540
+ objectsWrapFullMinSize
541
+ // another props
542
+ >
543
+ {children}
544
+ </MorphScroll>
545
+ ```
546
+
547
+ </ul></details>
548
+
549
+ <h2></h2>
550
+
551
+ #### PROGRESS AND RENDERING:
757
552
 
758
- </ul>
759
- </details>
553
+ <details>
554
+ <summary><strong><code>progressTrigger</code></strong>: <em>Triggers for the progress bar.</em></summary><br />
555
+ <ul>
556
+ <strong>Type:</strong> {<br />
557
+ wheel?: boolean;<br />
558
+ content?: boolean;<br />
559
+ progressElement?: boolean | React.ReactNode;<br />
560
+ arrows?: boolean | { size?: number; element?: React.ReactNode };<br />
561
+ }<br />
562
+ <br />
563
+ <strong>Default:</strong> { wheel: true }<br />
564
+ <br />
565
+ <strong>Description:</strong> <em><br />
566
+ This is one of the most important parameters, allowing you to define how users interact with the progress bar and customize its appearance.<br />
567
+ <br />
568
+ <ul>
569
+ <li>The <code>wheel</code> property determines whether the progress bar responds to mouse wheel scrolling.</li>
570
+ <li>The <code>content</code> property enables interaction by clicking and dragging anywhere within the scrollable content to move it.</li>
571
+ <li>The <code>progressElement</code> property defines whether the progress bar is controlled by a custom element. If your custom scroll element is not ready yet, you can simply pass <code>true</code>, which will display the browser's default scrollbar when <code>type="scroll"</code> is used. Alternatively, if <code>type="slider"</code> is set, a <code>sliderBar</code> element will be created, containing multiple <code>sliderElem</code> elements representing progress. Depending on the position, one of these elements will always have the <code>active</code> class.</li>
572
+ <li>The <code>arrows</code> property allows you to add custom arrows to the progress bar. You can either specify a <code>size</code> for the arrows and provide a custom <code>element</code>.</li>
573
+ </ul></em><br />
574
+ <br />
575
+ <strong>Example:</strong>
576
+
577
+ ```tsx
578
+ <MorphScroll
579
+ progressTrigger={{
580
+ wheel: true,
581
+ progressElement: <div className="your-scroll-thumb" />,
582
+ }}
583
+ // another props
584
+ >
585
+ {children}
586
+ </MorphScroll>
587
+ ```
588
+
589
+ </ul></details>
590
+
591
+ <h2></h2>
592
+
593
+ <details>
594
+ <summary><strong><code>render</code></strong>: <em>Types of rendering for optimization.</em></summary><br />
595
+ <ul>
596
+ <strong>Type:</strong><br />
597
+ | { type: "default" }<br />
598
+ | { type: "lazy"; rootMargin?: number | number[]; onVisible?: (key: string) => void }<br />
599
+ | { type: "virtual"; rootMargin?: number | number[] }<br />
600
+ <br />
601
+ <strong>Default:</strong> { type: "default" }<br />
602
+ <br />
603
+ <strong>Description:</strong> <em><br />
604
+ This parameter defines the rendering type for optimization.<br />
605
+ <br />
606
+ <ul>
607
+ <li>With <code>default</code>, no optimizations are applied.</li>
608
+ <li>With <code>lazy</code>, containers are created but do not load content until they enter the viewport. The <code>rootMargin</code> property controls the threshold for loading, and the <code>onVisible</code> callback function can be used to trigger actions when a container becomes visible for each scrollable object and provides the key of the first element in the container.</li>
609
+ <li>With <code>virtual</code>, a container is created for each scrollable object, and its absolute positioning is calculated based on <code>scrollTop</code> and scroll area dimensions. Rendering is dynamically adjusted according to the scroll position. The <code>rootMargin</code> property can also be used to extend the rendering area.</li>
610
+ </ul><br />
611
+ <br />
612
+ ⚠ Note:<br />
613
+ <ul>
614
+ <li>The <code>onVisible</code> property is the same as in <code>IntersectionTracker/onVisible</code>.</li>
615
+ <li>
616
+ The <code>rootMargin</code> property accepts either a single number or an array of numbers.
617
+ <ul>
618
+ <li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
619
+ <li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
620
+ </ul>
621
+ </li>
622
+ <li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
623
+ </ul></em><br />
624
+ <br />
625
+ <strong>Example:</strong>
626
+
627
+ ```tsx
628
+ <MorphScroll
629
+ render={{ type: "virtual" }}
630
+ // render={{
631
+ // type: "lazy",
632
+ // rootMargin: [0, 100],
633
+ // onVisible: () => console.log("visible"))
634
+ // }}
635
+ // another props
636
+ >
637
+ {children}
638
+ </MorphScroll>
639
+ ```
640
+
641
+ </ul></details>
642
+
643
+ <h2></h2>
644
+
645
+ <details>
646
+ <summary><strong><code>emptyElements</code></strong>: <em>Handling of empty scroll elements.</em></summary><br />
647
+ <ul>
648
+ <strong>Type:</strong><br />
649
+ | {
650
+ mode: "clear";
651
+ clickTrigger?: { selector: string; delay?: number };
652
+ }<br />
653
+ | {
654
+ mode: "fallback";
655
+ element?: React.ReactNode;
656
+ clickTrigger?: { selector: string; delay?: number };
657
+ }<br /><br />
658
+ <strong>Description:</strong> <em><br />
659
+ If certain components might return nothing during rendering, this parameter helps manage them. The check and subsequent replacement with a fallback element or removal occur after the scroll elements are rendered. Due to this, when dynamically displaying elements in different <code>render</code> modes, you may notice slight position shifts during fast scrolling, as empty elements are removed, causing subsequent elements to reposition.<br />
660
+ <br />
661
+ <ul>
662
+ <li><code>mode: "clear"</code> – automatically removes empty elements, eliminating unnecessary gaps in the scroll list.</li>
663
+ <li><code>mode: "fallback"</code> – replaces empty elements with a specified fallback component. By default, it uses the <code>fallback</code> props value, but you can also pass a separate placeholder to <code>element</code>.</li>
664
+ </ul><br />
665
+ <br />
666
+ <code>clickTrigger</code> – if elements are removed via a click action, this property ensures cleanup is triggered accordingly. It accepts an object with a <code>selector</code> (such as a delete button’s class) and an optional <code>delay</code> (a delay in milliseconds to accommodate animations or complex removals).<br />
667
+ <br />
668
+ ⚠ Note:<br />
669
+ For clarification, the cleanup will occur on the initial render, when the number of passed elements changes, on scroll, and on click if you use <code>clickTrigger</code>.</em><br />
670
+ <br />
671
+ <strong>Example:</strong>
672
+
673
+ ```tsx
674
+ <MorphScroll
675
+ emptyElements={{
676
+ mode: "clear",
677
+ clickTrigger: { selector: ".close-button" },
678
+ }}
679
+ // emptyElements={{
680
+ // mode: "fallback",
681
+ // clickTrigger: {
682
+ // selector: ".close-button",
683
+ // delay: 100,
684
+ // },
685
+ // }}
686
+ // another props
687
+ >
688
+ {children}
689
+ </MorphScroll>
690
+ ```
691
+
692
+ </ul></details>
693
+
694
+ <h2></h2>
695
+
696
+ <details>
697
+ <summary><strong><code>suspending</code></strong>: <em>Adds React Suspense.</em></summary><br />
698
+ <ul>
699
+ <strong>Type:</strong> boolean<br />
700
+ <br />
701
+ <strong>Default:</strong> false<br />
702
+ <br />
703
+ <strong>Description:</strong> <em><br />
704
+ This parameter adds React Suspense to the MorphScroll component for asynchronous rendering.</em><br />
705
+ <br />
706
+ <strong>Example:</strong>
707
+
708
+ ```tsx
709
+ <MorphScroll
710
+ suspending
711
+ // another props
712
+ >
713
+ {children}
714
+ </MorphScroll>
715
+ ```
716
+
717
+ </ul></details>
718
+
719
+ <h2></h2>
720
+
721
+ <details>
722
+ <summary><strong><code>fallback</code></strong>: <em>Fallback element.</em></summary><br />
723
+ <ul>
724
+ <strong>Type:</strong> React.ReactNode<br />
725
+ <br />
726
+ <strong>Description:</strong> <em><br />
727
+ This parameter sets the fallback element for custom element. It will be used for <code>emptyElements</code> in <code>mode: "fallback"</code> or when <code>suspending</code> is enabled.</em><br />
728
+ <br />
729
+ <strong>Example:</strong>
730
+
731
+ ```tsx
732
+ <MorphScroll
733
+ fallback={<div>Loading...</div>}
734
+ // another props
735
+ >
736
+ {children}
737
+ </MorphScroll>
738
+ ```
739
+
740
+ </ul></details>
741
+
742
+ </div>
760
743
 
761
744
  <h2></h2>
762
745
 
@@ -766,129 +749,125 @@ npm install morphing-scroll
766
749
 
767
750
  - ### Props:
768
751
 
769
- <details>
770
- <summary><strong><code>children</code></strong>: <em>Render-prop function for size updates and adding content.</em></summary><br />
771
- <ul>
772
- <strong>Type:</strong> (rect: DOMRectReadOnly) => React.ReactNode<br />
773
- <br />
774
- <strong>Description:</strong> <em><br />
775
- Instead of a standard <code>children</code> prop, this component uses a <strong>render-prop function</strong> to pass size updates to its children. You can use it similarly to a regular <code>children</code> prop inside the component.<br />
776
- <br />
777
- The function receives an object of type <code>DOMRectReadOnly</code> with the following properties:
752
+ <div>
753
+
754
+ <details>
755
+ <summary><strong><code>children</code></strong>: <em>Render-prop function for size updates and adding content.</em></summary><br />
778
756
  <ul>
779
- <li><code>x</code> - The X-coordinate of the top-left corner of the element.</li>
780
- <li><code>y</code> - The Y-coordinate of the top-left corner of the element.</li>
781
- <li><code>width</code> - The width of the observed element’s content box.</li>
782
- <li><code>height</code> - The height of the observed element’s content box.</li>
783
- <li><code>top</code> - The distance from the top of the element to its parent's top. Equal to <code>y</code>.</li>
784
- <li><code>left</code> - The distance from the left of the element to its parent's left. Equal to <code>x</code>.</li>
785
- <li><code>right</code> - The distance from the left of the parent to the right edge of the element (<code>left</code> + <code>width</code>).</li>
786
- <li><code>bottom</code> - The distance from the top of the parent to the bottom edge of the element (<code>top</code> + <code>height</code>).</li>
787
- </ul><br />
788
- <br />
789
- ⚠ This is a non-standard prop that you might be used to using this is render-prop function receiving the container's size.</em><br />
790
- <br />
791
- <strong>Example:</strong>
792
-
793
- ```tsx
794
- <ResizeTracker
795
- // another props
796
- >
797
- {(rect) => (
798
- <p>
799
- Width: {rect.width}, Height: {rect.height}
800
- </p>
801
- )}
802
- </ResizeTracker>
803
- ```
804
-
805
- </ul>
806
-
807
- </details>
808
-
809
- <h2></h2>
810
-
811
- <details>
812
- <summary><strong><code>style</code></strong>: <em>Applies inline styles to the container.</em></summary><br />
813
- <ul>
814
- <strong>Type:</strong> React.CSSProperties<br />
815
- <br />
816
- <strong>Example:</strong>
817
-
818
- ```tsx
819
- <ResizeTracker style={{ backgroundColor: "blue" }}>
820
- {(rect) => (
821
- // content
822
- )}
823
- </ResizeTracker>
824
- ```
825
-
826
- </ul>
827
-
828
- </details>
829
-
830
- <h2></h2>
831
-
832
- <details>
833
- <summary><strong><code>measure</code></strong>: <em>Defines the measurement strategy.</em></summary><br />
834
- <ul>
835
- <strong>Type:</strong> "inner" | "outer" | "all"<br />
836
- <br />
837
- <strong>Default:</strong> "inner"<br />
838
- <br />
839
- <strong>Description:</strong><br />
840
- <em>This prop determines what is being measured by automatically applying inline styles that affect width and height.<br />
841
- <br />
842
- - The default value <code>"inner"</code> sets <code>width: "max-content"</code> and <code>height: "max-content"</code>, measuring the size of child elements.<br />
843
- - The <code>"outer"</code> value measures the parent element by setting <code>minWidth: "100%"</code> and <code>minHeight: "100%"</code>.<br />
844
- - The <code>"all"</code> value combines the styles of both <code>"inner"</code> and <code>"outer"</code>, allowing measurement of both the parent and child elements.<br />
845
- <br />
846
- ⚠ Note: Be cautious when overriding styles via the <code>style</code> prop, as it may interfere with the styles applied by <code>measure</code>, leading to unexpected behavior.</em><br />
847
- <br />
848
- <strong>Example:</strong>
849
-
850
- ```tsx
851
- <ResizeTracker measure="all">
852
- {(rect) => (
853
- // content
854
- )}
855
- </ResizeTracker>
856
- ```
857
-
858
- </ul>
859
-
860
- </details>
861
-
862
- <h2></h2>
863
-
864
- <details>
865
- <summary><strong><code>onResize</code></strong>: <em>Callback triggered on size changes.</em></summary><br />
866
- <ul>
867
- <strong>Type:</strong> (rect: Partial<DOMRectReadOnly>) => void<br />
868
- <br />
869
- <strong>Description:</strong><br />
870
- <em>A callback function that is triggered whenever the observed element's dimensions change.<br />
871
- The function receives an object containing the updated size properties.</em><br />
872
- <br />
873
- <strong>Example:</strong>
874
-
875
- ```tsx
876
- <ResizeTracker
877
- onResize={(rect) => {
878
- console.log("New size:", rect);
879
- }}
880
- >
881
- {(rect) => (
882
- // content
883
- )}
884
- </ResizeTracker>
885
- ```
886
-
887
- </ul>
888
-
889
- </details>
890
-
891
- <h2></h2>
757
+ <strong>Type:</strong> (rect: DOMRectReadOnly) => React.ReactNode<br />
758
+ <br />
759
+ <strong>Description:</strong> <em><br />
760
+ Instead of a standard <code>children</code> prop, this component uses a <strong>render-prop function</strong> to pass size updates to its children. You can use it similarly to a regular <code>children</code> prop inside the component.<br />
761
+ <br />
762
+ The function receives an object of type <code>DOMRectReadOnly</code> with the following properties:
763
+ <ul>
764
+ <li><code>x</code> - The X-coordinate of the top-left corner of the element.</li>
765
+ <li><code>y</code> - The Y-coordinate of the top-left corner of the element.</li>
766
+ <li><code>width</code> - The width of the observed element’s content box.</li>
767
+ <li><code>height</code> - The height of the observed element’s content box.</li>
768
+ <li><code>top</code> - The distance from the top of the element to its parent's top. Equal to <code>y</code>.</li>
769
+ <li><code>left</code> - The distance from the left of the element to its parent's left. Equal to <code>x</code>.</li>
770
+ <li><code>right</code> - The distance from the left of the parent to the right edge of the element (<code>left</code> + <code>width</code>).</li>
771
+ <li><code>bottom</code> - The distance from the top of the parent to the bottom edge of the element (<code>top</code> + <code>height</code>).</li>
772
+ </ul><br />
773
+ <br />
774
+ ⚠ This is a non-standard prop that you might be used to using this is render-prop function receiving the container's size.</em><br />
775
+ <br />
776
+ <strong>Example:</strong>
777
+
778
+ ```tsx
779
+ <ResizeTracker
780
+ // another props
781
+ >
782
+ {(rect) => (
783
+ <p>
784
+ Width: {rect.width}, Height: {rect.height}
785
+ </p>
786
+ )}
787
+ </ResizeTracker>
788
+ ```
789
+
790
+ </ul></details>
791
+
792
+ <h2></h2>
793
+
794
+ <details>
795
+ <summary><strong><code>style</code></strong>: <em>Applies inline styles to the container.</em></summary><br />
796
+ <ul>
797
+ <strong>Type:</strong> React.CSSProperties<br />
798
+ <br />
799
+ <strong>Example:</strong>
800
+
801
+ ```tsx
802
+ <ResizeTracker style={{ backgroundColor: "blue" }}>
803
+ {(rect) => (
804
+ // content
805
+ )}
806
+ </ResizeTracker>
807
+ ```
808
+
809
+ </ul></details>
810
+
811
+ <h2></h2>
812
+
813
+ <details>
814
+ <summary><strong><code>measure</code></strong>: <em>Defines the measurement strategy.</em></summary><br />
815
+ <ul>
816
+ <strong>Type:</strong> "inner" | "outer" | "all"<br />
817
+ <br />
818
+ <strong>Default:</strong> "inner"<br />
819
+ <br />
820
+ <strong>Description:</strong><br />
821
+ <em>This prop determines what is being measured by automatically applying inline styles that affect width and height.<br />
822
+ <br />
823
+ - The default value <code>"inner"</code> sets <code>width: "max-content"</code> and <code>height: "max-content"</code>, measuring the size of child elements.<br />
824
+ - The <code>"outer"</code> value measures the parent element by setting <code>minWidth: "100%"</code> and <code>minHeight: "100%"</code>.<br />
825
+ - The <code>"all"</code> value combines the styles of both <code>"inner"</code> and <code>"outer"</code>, allowing measurement of both the parent and child elements.<br />
826
+ <br />
827
+ ⚠ Note: Be cautious when overriding styles via the <code>style</code> prop, as it may interfere with the styles applied by <code>measure</code>, leading to unexpected behavior.</em><br />
828
+ <br />
829
+ <strong>Example:</strong>
830
+
831
+ ```tsx
832
+ <ResizeTracker measure="all">
833
+ {(rect) => (
834
+ // content
835
+ )}
836
+ </ResizeTracker>
837
+ ```
838
+
839
+ </ul></details>
840
+
841
+ <h2></h2>
842
+
843
+ <details>
844
+ <summary><strong><code>onResize</code></strong>: <em>Callback triggered on size changes.</em></summary><br />
845
+ <ul>
846
+ <strong>Type:</strong> (rect: Partial<DOMRectReadOnly>) => void<br />
847
+ <br />
848
+ <strong>Description:</strong><br />
849
+ <em>A callback function that is triggered whenever the observed element's dimensions change.<br />
850
+ The function receives an object containing the updated size properties.</em><br />
851
+ <br />
852
+ <strong>Example:</strong>
853
+
854
+ ```tsx
855
+ <ResizeTracker
856
+ onResize={(rect) => {
857
+ console.log("New size:", rect);
858
+ }}
859
+ >
860
+ {(rect) => (
861
+ // content
862
+ )}
863
+ </ResizeTracker>
864
+ ```
865
+
866
+ </ul></details>
867
+
868
+ <h2></h2>
869
+
870
+ </div>
892
871
 
893
872
  - ### Link:
894
873
 
@@ -902,193 +881,183 @@ npm install morphing-scroll
902
881
 
903
882
  - ### Props:
904
883
 
905
- <details>
906
- <summary><strong><code>children</code></strong>: <em>Custom user content.</em></summary><br />
907
- <ul>
908
- <strong>Type:</strong> React.ReactNode<br />
909
- <br />
910
- <strong>Example:</strong>
911
-
912
- ```tsx
913
- <IntersectionTracker>{children}</IntersectionTracker>
914
- ```
915
-
916
- </ul>
917
-
918
- </details>
919
-
920
- <h2></h2>
921
-
922
- <details>
923
- <summary><strong><code>style</code></strong>: <em>Applies inline styles to the container.</em></summary><br />
924
- <ul>
925
- <strong>Type:</strong> React.CSSProperties<br />
926
- <br />
927
- <strong>Example:</strong>
928
-
929
- ```tsx
930
- <IntersectionTracker style={{ backgroundColor: "blue" }}>
931
- {children}
932
- </IntersectionTracker>
933
- ```
934
-
935
- </ul>
936
-
937
- </details>
938
-
939
- <h2></h2>
940
-
941
- <details>
942
- <summary><strong><code>root</code></strong>: <em>Defines the observation area.</em></summary><br />
943
- <ul>
944
- <strong>Type:</strong> Element | null<br />
945
- <br />
946
- <strong>Default:</strong> null (window)<br />
947
- <br />
948
- <strong>Description:</strong> <em><br />
949
- Specifies the element that serves as the bounding box for the intersection observation.
950
- If provided, it must be an ancestor of the observed element.<br />
951
- <br />
952
- If set to <code>null</code> (default), the window is used as the observation area.</em><br />
953
- <br />
954
- <strong>Example:</strong>
955
-
956
- ```tsx
957
- <IntersectionTracker root={document.getElementById("root")}>
958
- {children}
959
- </IntersectionTracker>
960
- ```
961
-
962
- </ul>
963
-
964
- </details>
965
-
966
- <h2></h2>
967
-
968
- <details>
969
- <summary><strong><code>rootMargin</code></strong>: <em>Sets the margin around the root element.</em></summary><br />
970
- <ul>
971
- <strong>Type:</strong> number | number[]<br />
972
- <br />
973
- <strong>Description:</strong> <em><br />
974
- Defines an offset around the root element, expanding or shrinking the observed area.<br />
975
- <br />
976
- Accepts a single number or an array for fine-tuned control:<br />
884
+ <div>
885
+
886
+ <details>
887
+ <summary><strong><code>children</code></strong>: <em>Custom user content.</em></summary><br />
977
888
  <ul>
978
- <li>A <strong>single number</strong> sets the same margin on all sides.</li>
979
- <li>A <strong>two-value array</strong> <code>[topBottom, leftRight]</code> applies margins vertically and horizontally.</li>
980
- <li>A <strong>four-value array</strong> <code>[top, right, bottom, left]</code> allows full control over each side.</li>
981
- </ul>
982
- <br />
983
- Margins are converted to <code>px</code> values internally.</em><br />
984
- <br />
985
- <strong>Example:</strong>
986
-
987
- ```tsx
988
- <IntersectionTracker
989
- rootMargin={10}
990
- // rootMargin={[10, 20]}
991
- // rootMargin={[10, 20, 10, 20]}
992
- >
993
- {children}
994
- </IntersectionTracker>
995
- ```
996
-
997
- </ul>
998
-
999
- </details>
1000
-
1001
- <h2></h2>
1002
-
1003
- <details>
1004
- <summary><strong><code>threshold</code></strong>: <em>Defines when the callback is triggered.</em></summary><br />
1005
- <ul>
1006
- <strong>Type:</strong> number | number[]<br />
1007
- <br />
1008
- <strong>Description:</strong> <em><br />
1009
- .Specifies at what percentage of the observed element’s visibility the callback should be executed.<br />
1010
- <br />
889
+ <strong>Type:</strong> React.ReactNode<br />
890
+ <br />
891
+ <strong>Example:</strong>
892
+
893
+ ```tsx
894
+ <IntersectionTracker>{children}</IntersectionTracker>
895
+ ```
896
+
897
+ </ul></details>
898
+
899
+ <h2></h2>
900
+
901
+ <details>
902
+ <summary><strong><code>style</code></strong>: <em>Applies inline styles to the container.</em></summary><br />
1011
903
  <ul>
1012
- <li>A <strong>single number</strong> (e.g., <code>0.5</code>) triggers when that fraction of the element is visible.</li>
1013
- <li>A <strong>array of numbers</strong> (e.g., <code>[0, 0.5, 1]</code>) triggers the callback multiple times at different visibility levels.</li>
1014
- </ul>
1015
- <br />
1016
- A value of <code>0</code> means the callback fires when any part of the element appears, while <code>1</code> means the element must be fully visible.</em><br />
1017
- <br />
1018
- <strong>Example:</strong>
1019
-
1020
- ```tsx
1021
- <IntersectionTracker
1022
- threshold={0.5}
1023
- // threshold={[0, 0.5, 1]}
1024
- >
1025
- {children}
1026
- </IntersectionTracker>
1027
- ```
1028
-
1029
- </ul>
1030
-
1031
- </details>
1032
-
1033
- <h2></h2>
1034
-
1035
- <details>
1036
- <summary><strong><code>visibleContent</code></strong>: <em>Makes all elements always visible.</em></summary><br />
1037
- <ul>
1038
- <strong>Type:</strong> boolean<br />
1039
- <br />
1040
- <strong>Default:</strong> false<br />
1041
- <br />
1042
- <strong>Description:</strong> <em><br />
1043
- If set to `true`, the tracked elements will always be visible, regardless of their actual intersection status.
1044
- <br />
1045
- This can be useful for testing purposes or when using the <code>onVisible</code> callback, ensuring it continues to trigger whenever the element enters the viewport.</em><br />
1046
- <br />
1047
- <strong>Example:</strong>
1048
-
1049
- ```tsx
1050
- <IntersectionTracker visibleContent>{children}</IntersectionTracker>
1051
- ```
1052
-
1053
- </ul>
1054
-
1055
- </details>
1056
-
1057
- <h2></h2>
1058
-
1059
- <details>
1060
- <summary><strong><code>onVisible</code></strong>: <em>Callback function triggered when the element becomes visible.</em></summary><br />
1061
- <ul>
1062
- <strong>Type:</strong> (key: string) => void<br />
1063
- <br />
1064
- <strong>Description:</strong> <em><br />
1065
- A callback function that is invoked when the observed element enters the viewport or the defined observation area.<br />
1066
- <br />
1067
- The callback receives the <code>key</code> of the first child element as a parameter.<br />
1068
- This can be useful for lazy loading, analytics tracking, animations, or any other action that needs to be triggered when an element becomes visible.<br />
1069
- <br />
1070
- ⚠ Note:<br />
1071
- Instead of checking if <code>key</code> equals the element’s key name, use <code>includes</code> for verification. React may modify key names by prefixing them with special characters like <code>.$</code>, making direct equality checks unreliable and more expensive 💵.</em><br />
1072
- <br />
1073
- <strong>Example:</strong>
1074
-
1075
- ```tsx
1076
- <IntersectionTracker
1077
- onVisible={(key) => {
1078
- if (key.includes("elementId")) {
1079
- // do something
1080
- }
1081
- }}
1082
- >
1083
- {children}
1084
- </IntersectionTracker>
1085
- ```
904
+ <strong>Type:</strong> React.CSSProperties<br />
905
+ <br />
906
+ <strong>Example:</strong>
1086
907
 
1087
- </ul>
908
+ ```tsx
909
+ <IntersectionTracker style={{ backgroundColor: "blue" }}>
910
+ {children}
911
+ </IntersectionTracker>
912
+ ```
1088
913
 
1089
- </details>
914
+ </ul></details>
1090
915
 
1091
- <h2></h2>
916
+ <h2></h2>
917
+
918
+ <details>
919
+ <summary><strong><code>root</code></strong>: <em>Defines the observation area.</em></summary><br />
920
+ <ul>
921
+ <strong>Type:</strong> Element | null<br />
922
+ <br />
923
+ <strong>Default:</strong> null (window)<br />
924
+ <br />
925
+ <strong>Description:</strong> <em><br />
926
+ Specifies the element that serves as the bounding box for the intersection observation.
927
+ If provided, it must be an ancestor of the observed element.<br />
928
+ <br />
929
+ If set to <code>null</code> (default), the window is used as the observation area.</em><br />
930
+ <br />
931
+ <strong>Example:</strong>
932
+
933
+ ```tsx
934
+ <IntersectionTracker root={document.getElementById("root")}>
935
+ {children}
936
+ </IntersectionTracker>
937
+ ```
938
+
939
+ </ul></details>
940
+
941
+ <h2></h2>
942
+
943
+ <details>
944
+ <summary><strong><code>rootMargin</code></strong>: <em>Sets the margin around the root element.</em></summary><br />
945
+ <ul>
946
+ <strong>Type:</strong> number | number[]<br />
947
+ <br />
948
+ <strong>Description:</strong> <em><br />
949
+ Defines an offset around the root element, expanding or shrinking the observed area.<br />
950
+ <br />
951
+ Accepts a single number or an array for fine-tuned control:<br />
952
+ <ul>
953
+ <li>A <strong>single number</strong> sets the same margin on all sides.</li>
954
+ <li>A <strong>two-value array</strong> <code>[topBottom, leftRight]</code> applies margins vertically and horizontally.</li>
955
+ <li>A <strong>four-value array</strong> <code>[top, right, bottom, left]</code> allows full control over each side.</li>
956
+ </ul>
957
+ <br />
958
+ Margins are converted to <code>px</code> values internally.</em><br />
959
+ <br />
960
+ <strong>Example:</strong>
961
+
962
+ ```tsx
963
+ <IntersectionTracker
964
+ rootMargin={10}
965
+ // rootMargin={[10, 20]}
966
+ // rootMargin={[10, 20, 10, 20]}
967
+ >
968
+ {children}
969
+ </IntersectionTracker>
970
+ ```
971
+
972
+ </ul></details>
973
+
974
+ <h2></h2>
975
+
976
+ <details>
977
+ <summary><strong><code>threshold</code></strong>: <em>Defines when the callback is triggered.</em></summary><br />
978
+ <ul>
979
+ <strong>Type:</strong> number | number[]<br />
980
+ <br />
981
+ <strong>Description:</strong> <em><br />
982
+ .Specifies at what percentage of the observed element’s visibility the callback should be executed.<br />
983
+ <br />
984
+ <ul>
985
+ <li>A <strong>single number</strong> (e.g., <code>0.5</code>) triggers when that fraction of the element is visible.</li>
986
+ <li>A <strong>array of numbers</strong> (e.g., <code>[0, 0.5, 1]</code>) triggers the callback multiple times at different visibility levels.</li>
987
+ </ul>
988
+ <br />
989
+ A value of <code>0</code> means the callback fires when any part of the element appears, while <code>1</code> means the element must be fully visible.</em><br />
990
+ <br />
991
+ <strong>Example:</strong>
992
+
993
+ ```tsx
994
+ <IntersectionTracker
995
+ threshold={0.5}
996
+ // threshold={[0, 0.5, 1]}
997
+ >
998
+ {children}
999
+ </IntersectionTracker>
1000
+ ```
1001
+
1002
+ </ul></details>
1003
+
1004
+ <h2></h2>
1005
+
1006
+ <details>
1007
+ <summary><strong><code>visibleContent</code></strong>: <em>Makes all elements always visible.</em></summary><br />
1008
+ <ul>
1009
+ <strong>Type:</strong> boolean<br />
1010
+ <br />
1011
+ <strong>Default:</strong> false<br />
1012
+ <br />
1013
+ <strong>Description:</strong> <em><br />
1014
+ If set to `true`, the tracked elements will always be visible, regardless of their actual intersection status.
1015
+ <br />
1016
+ This can be useful for testing purposes or when using the <code>onVisible</code> callback, ensuring it continues to trigger whenever the element enters the viewport.</em><br />
1017
+ <br />
1018
+ <strong>Example:</strong>
1019
+
1020
+ ```tsx
1021
+ <IntersectionTracker visibleContent>{children}</IntersectionTracker>
1022
+ ```
1023
+
1024
+ </ul></details>
1025
+
1026
+ <h2></h2>
1027
+
1028
+ <details>
1029
+ <summary><strong><code>onVisible</code></strong>: <em>Callback function triggered when the element becomes visible.</em></summary><br />
1030
+ <ul>
1031
+ <strong>Type:</strong> (key: string) => void<br />
1032
+ <br />
1033
+ <strong>Description:</strong> <em><br />
1034
+ A callback function that is invoked when the observed element enters the viewport or the defined observation area.<br />
1035
+ <br />
1036
+ The callback receives the <code>key</code> of the first child element as a parameter.<br />
1037
+ This can be useful for lazy loading, analytics tracking, animations, or any other action that needs to be triggered when an element becomes visible.<br />
1038
+ <br />
1039
+ ⚠ Note:<br />
1040
+ Instead of checking if <code>key</code> equals the element’s key name, use <code>includes</code> for verification. React may modify key names by prefixing them with special characters like <code>.$</code>, making direct equality checks unreliable and more expensive 💵.</em><br />
1041
+ <br />
1042
+ <strong>Example:</strong>
1043
+
1044
+ ```tsx
1045
+ <IntersectionTracker
1046
+ onVisible={(key) => {
1047
+ if (key.includes("elementId")) {
1048
+ // do something
1049
+ }
1050
+ }}
1051
+ >
1052
+ {children}
1053
+ </IntersectionTracker>
1054
+ ```
1055
+
1056
+ </ul></details>
1057
+
1058
+ <h2></h2>
1059
+
1060
+ </div>
1092
1061
 
1093
1062
  - ### Link:
1094
1063