morphing-scroll 1.3.3 → 1.4.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +922 -443
- package/index.d.ts +79 -61
- package/index.js +1 -1
- package/package.json +3 -5
package/README.md
CHANGED
|
@@ -1,22 +1,25 @@
|
|
|
1
|
-
|
|
2
|
-
<img src="https://drive.google.com/uc?export=view&id=1mpb5TAElX3Xla4sGFISp4bQMu0zuNJaa" alt="logo"/>
|
|
3
|
-
</div>
|
|
1
|
+
|
|
4
2
|
|
|
5
|
-
##
|
|
3
|
+
##
|
|
4
|
+
|
|
5
|
+
### 〈♦ Table of contents 〉
|
|
6
6
|
|
|
7
7
|
- [About](#-about-)
|
|
8
8
|
- [Installation](#-installation-)
|
|
9
|
-
- [MorphScroll](#-
|
|
10
|
-
- [ResizeTracker](#-
|
|
11
|
-
- [IntersectionTracker](#-
|
|
12
|
-
- [More](#-More-)
|
|
9
|
+
- [MorphScroll](#-morphscroll-)
|
|
10
|
+
- [ResizeTracker](#-resizetracker-)
|
|
11
|
+
- [IntersectionTracker](#-intersectiontracker-)
|
|
13
12
|
- [API](#-api-)
|
|
14
13
|
|
|
15
|
-
##
|
|
14
|
+
##
|
|
15
|
+
|
|
16
|
+
### 〈♦ About 〉
|
|
16
17
|
|
|
17
18
|
`morphing-scroll` is a `React` library designed to optimize the rendering of data lists. It leverages virtual rendering and lazy loading to handle large datasets efficiently, significantly enhancing performance. The library also resolves cross-browser inconsistencies in scroll element rendering by replacing them with custom ones. Additionally, it provides convenient horizontal scrolling with flexible content movement options.
|
|
18
19
|
|
|
19
|
-
##
|
|
20
|
+
##
|
|
21
|
+
|
|
22
|
+
### 〈♦ Installation 〉
|
|
20
23
|
|
|
21
24
|
To install the library, use the following command:
|
|
22
25
|
|
|
@@ -24,603 +27,1079 @@ To install the library, use the following command:
|
|
|
24
27
|
npm install morphing-scroll
|
|
25
28
|
```
|
|
26
29
|
|
|
27
|
-
##
|
|
30
|
+
##
|
|
31
|
+
|
|
32
|
+
### 〈♦ MorphScroll 〉
|
|
28
33
|
|
|
29
34
|
`MorphScroll` is the main component of the library responsible for displaying your data.
|
|
30
35
|
|
|
31
|
-
### Props:
|
|
36
|
+
- ### Props:
|
|
32
37
|
|
|
33
|
-
|
|
38
|
+
#### GENERAL SETTINGS:
|
|
34
39
|
|
|
35
|
-
- **`className`:** _Additional classes for the component._
|
|
36
40
|
<details>
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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>
|
|
45
61
|
|
|
46
|
-
|
|
47
|
-
<MorphScroll
|
|
48
|
-
className="your-class"
|
|
49
|
-
// another props
|
|
50
|
-
>
|
|
51
|
-
{children}
|
|
52
|
-
</MorphScroll>
|
|
53
|
-
```
|
|
62
|
+
##
|
|
54
63
|
|
|
64
|
+
<details>
|
|
65
|
+
<summary><strong><code>children</code></strong> : <em>Custom user content.</em></summary><br />
|
|
66
|
+
<ul>
|
|
67
|
+
<strong>Type:</strong> React.ReactNode<br />
|
|
68
|
+
<br />
|
|
69
|
+
<strong>Description:</strong> <em><br />
|
|
70
|
+
This is where you can pass your list elements.<br />
|
|
71
|
+
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 />
|
|
72
|
+
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 />
|
|
73
|
+
<br />
|
|
74
|
+
<strong>Example:</strong>
|
|
75
|
+
|
|
76
|
+
```tsx
|
|
77
|
+
<MorphScroll
|
|
78
|
+
// props
|
|
79
|
+
>
|
|
80
|
+
{children}
|
|
81
|
+
</MorphScroll>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
</ul>
|
|
55
85
|
</details>
|
|
56
|
-
<h2>
|
|
57
86
|
|
|
58
|
-
|
|
87
|
+
##
|
|
88
|
+
|
|
89
|
+
#### SCROLL SETTINGS:
|
|
90
|
+
|
|
59
91
|
<details>
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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>
|
|
115
|
+
</details>
|
|
70
116
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
117
|
+
##
|
|
118
|
+
|
|
119
|
+
<details>
|
|
120
|
+
<summary><strong><code>direction</code></strong> : <em>Scrolling direction.</em></summary><br />
|
|
121
|
+
<ul>
|
|
122
|
+
<strong>Type:</strong> "x" | "y"<br />
|
|
123
|
+
<br />
|
|
124
|
+
<strong>Default:</strong> "y"<br />
|
|
125
|
+
<br />
|
|
126
|
+
<strong>Description:</strong> <em><br />
|
|
127
|
+
This parameter changes the scroll or slider type direction based on the provided value.<br />
|
|
128
|
+
You can set it to horizontal or vertical to customize the component according to your needs.</em><br />
|
|
129
|
+
<br />
|
|
130
|
+
<strong>Example:</strong>
|
|
131
|
+
|
|
132
|
+
```tsx
|
|
133
|
+
<MorphScroll
|
|
134
|
+
direction="x"
|
|
135
|
+
// another props
|
|
136
|
+
>
|
|
137
|
+
{children}
|
|
138
|
+
</MorphScroll>
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
</ul>
|
|
142
|
+
</details>
|
|
78
143
|
|
|
144
|
+
##
|
|
145
|
+
|
|
146
|
+
<details>
|
|
147
|
+
<summary><strong><code>scrollTop</code></strong> : <em>Scroll position and animation duration.</em></summary><br />
|
|
148
|
+
<ul>
|
|
149
|
+
<strong>Type:</strong> {<br />
|
|
150
|
+
value: number | "end";<br />
|
|
151
|
+
duration?: number;<br />
|
|
152
|
+
updater?: boolean;<br />
|
|
153
|
+
}<br />
|
|
154
|
+
<br />
|
|
155
|
+
<strong>Default:</strong> { value: 0; duration: 200; updater: false }<br />
|
|
156
|
+
<br />
|
|
157
|
+
<strong>Description:</strong> <em><br />
|
|
158
|
+
This parameter allows you to set custom scroll values.<br />
|
|
159
|
+
<br />
|
|
160
|
+
The <code>value</code> property accepts numerical pixel values.<br />
|
|
161
|
+
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 />
|
|
162
|
+
<br />
|
|
163
|
+
The <code>duration</code> property determines the animation speed for scrolling in ms.</em><br />
|
|
164
|
+
<br />
|
|
165
|
+
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 />
|
|
166
|
+
<code>setScroll((prev) => ({ ...prev, value: 0, updater: !prev.updater }))</code></em><br />
|
|
167
|
+
<br />
|
|
168
|
+
<strong>Example:</strong>
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
171
|
+
<MorphScroll
|
|
172
|
+
scrollTop={{ value: 100; duration: 100 }}
|
|
173
|
+
// another props
|
|
174
|
+
>
|
|
175
|
+
{children}
|
|
176
|
+
</MorphScroll>
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
</ul>
|
|
79
180
|
</details>
|
|
80
181
|
|
|
81
|
-
|
|
182
|
+
##
|
|
82
183
|
|
|
83
|
-
|
|
84
|
-
<
|
|
85
|
-
<
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
184
|
+
<details>
|
|
185
|
+
<summary><strong><code>stopLoadOnScroll</code></strong> : <em>Stop loading when scrolling.</em></summary><br />
|
|
186
|
+
<ul>
|
|
187
|
+
<strong>Type:</strong> boolean<br />
|
|
188
|
+
<br />
|
|
189
|
+
<strong>Default:</strong> false<br />
|
|
190
|
+
<br />
|
|
191
|
+
<strong>Description:</strong> <em><br />
|
|
192
|
+
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 />
|
|
193
|
+
<br />
|
|
194
|
+
<strong>Example:</strong>
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
<MorphScroll
|
|
198
|
+
stopLoadOnScroll
|
|
199
|
+
// another props
|
|
200
|
+
>
|
|
201
|
+
{children}
|
|
202
|
+
</MorphScroll>
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
</ul>
|
|
206
|
+
</details>
|
|
97
207
|
|
|
98
|
-
|
|
99
|
-
<MorphScroll
|
|
100
|
-
type="slider"
|
|
101
|
-
// another props
|
|
102
|
-
>
|
|
103
|
-
{children}
|
|
104
|
-
</MorphScroll>
|
|
105
|
-
```
|
|
208
|
+
##
|
|
106
209
|
|
|
107
|
-
|
|
108
|
-
<
|
|
210
|
+
<details>
|
|
211
|
+
<summary><strong><code>onScrollValue</code></strong> : <em>Callback for scroll value.</em></summary><br />
|
|
212
|
+
<ul>
|
|
213
|
+
<strong>Type:</strong> (scroll: number) => void<br />
|
|
214
|
+
<br />
|
|
215
|
+
<strong>Description:</strong> <em><br />
|
|
216
|
+
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 />
|
|
217
|
+
<br />
|
|
218
|
+
<strong>Example:</strong>
|
|
219
|
+
|
|
220
|
+
```tsx
|
|
221
|
+
<MorphScroll
|
|
222
|
+
onScrollValue={
|
|
223
|
+
(scroll) => {
|
|
224
|
+
console.log("Scroll position:", scroll);
|
|
225
|
+
return scroll > 100;
|
|
226
|
+
},
|
|
227
|
+
}
|
|
228
|
+
// another props
|
|
229
|
+
>
|
|
230
|
+
{children}
|
|
231
|
+
</MorphScroll>
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
</ul>
|
|
235
|
+
</details>
|
|
236
|
+
|
|
237
|
+
##
|
|
109
238
|
|
|
110
|
-
- **`direction`:** _Scrolling direction._
|
|
111
239
|
<details>
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
240
|
+
<summary><strong><code>isScrolling</code></strong> : <em>Callback function for scroll status.</em></summary><br />
|
|
241
|
+
<ul>
|
|
242
|
+
<strong>Type:</strong> (motion: boolean) => void<br />
|
|
243
|
+
<br />
|
|
244
|
+
<strong>Description:</strong> <em><br />
|
|
245
|
+
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 />
|
|
246
|
+
<br />
|
|
247
|
+
<strong>Example:</strong>
|
|
248
|
+
|
|
249
|
+
```tsx
|
|
250
|
+
<MorphScroll
|
|
251
|
+
isScrolling={(motion) => {
|
|
252
|
+
console.log(motion ? "Scrolling..." : "Scroll stopped.");
|
|
253
|
+
}}
|
|
254
|
+
// another props
|
|
255
|
+
>
|
|
256
|
+
{children}
|
|
257
|
+
</MorphScroll>
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
</ul>
|
|
261
|
+
</details>
|
|
123
262
|
|
|
124
|
-
|
|
125
|
-
<MorphScroll
|
|
126
|
-
direction="x"
|
|
127
|
-
// another props
|
|
128
|
-
>
|
|
129
|
-
{children}
|
|
130
|
-
</MorphScroll>
|
|
131
|
-
```
|
|
263
|
+
##
|
|
132
264
|
|
|
265
|
+
#### VISUAL SETTINGS:
|
|
266
|
+
|
|
267
|
+
<details>
|
|
268
|
+
<summary><strong><code>size</code></strong> : <em>MorphScroll width and height.</em></summary><br />
|
|
269
|
+
<ul>
|
|
270
|
+
<strong>Type:</strong> number[]<br />
|
|
271
|
+
<br />
|
|
272
|
+
<strong>Description:</strong> <em><br />
|
|
273
|
+
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 />
|
|
274
|
+
<br />
|
|
275
|
+
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 />
|
|
276
|
+
<br />
|
|
277
|
+
⚠ Note:<br />
|
|
278
|
+
<ul>
|
|
279
|
+
<li>The values are specified following the <code>width/height</code> rule in pixels, regardless of the <code>direction</code>.</li>
|
|
280
|
+
<li>See the <code>ResizeTracker</code> section for more details.</li>
|
|
281
|
+
</ul></em><br />
|
|
282
|
+
<br />
|
|
283
|
+
<strong>Example:</strong>
|
|
284
|
+
|
|
285
|
+
```tsx
|
|
286
|
+
<MorphScroll
|
|
287
|
+
size={[100, 400]}
|
|
288
|
+
// another props
|
|
289
|
+
>
|
|
290
|
+
{children}
|
|
291
|
+
</MorphScroll>
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
</ul>
|
|
133
295
|
</details>
|
|
134
|
-
<h2>
|
|
135
296
|
|
|
136
|
-
|
|
297
|
+
##
|
|
298
|
+
|
|
137
299
|
<details>
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
300
|
+
<summary><strong><code>objectsSize</code> (required)</strong> : <em>Required: Size of cells for each object.</em></summary><br />
|
|
301
|
+
<ul>
|
|
302
|
+
<strong>Type:</strong> (number | "none" | "firstChild")[]<br />
|
|
303
|
+
<br />
|
|
304
|
+
<strong>Description:</strong> <em><br />
|
|
305
|
+
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 />
|
|
306
|
+
<br />
|
|
307
|
+
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 />
|
|
308
|
+
<br />
|
|
309
|
+
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 />
|
|
310
|
+
<br />
|
|
311
|
+
⚠ Note:<br />
|
|
312
|
+
The numbers are specified following the <code>width/height</code> rule, regardless of the <code>direction</code>.</em><br />
|
|
313
|
+
<br />
|
|
314
|
+
<strong>Example:</strong>
|
|
315
|
+
|
|
316
|
+
```tsx
|
|
317
|
+
<MorphScroll
|
|
318
|
+
objectsSize={[40, 40]}
|
|
319
|
+
// objectsSize={["none", "none"]}
|
|
320
|
+
// objectsSize={["firstChild", "firstChild"]}
|
|
321
|
+
// another props
|
|
322
|
+
>
|
|
323
|
+
{children}
|
|
324
|
+
</MorphScroll>
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
</ul>
|
|
328
|
+
</details>
|
|
150
329
|
|
|
151
|
-
|
|
152
|
-
<MorphScroll
|
|
153
|
-
scrollTop={{ value: 100; duration: 100 }}
|
|
154
|
-
// another props
|
|
155
|
-
>
|
|
156
|
-
{children}
|
|
157
|
-
</MorphScroll>
|
|
158
|
-
```
|
|
330
|
+
##
|
|
159
331
|
|
|
332
|
+
<details>
|
|
333
|
+
<summary><strong><code>gap</code></strong> : <em>Gap between cells.</em></summary><br />
|
|
334
|
+
<ul>
|
|
335
|
+
<strong>Type:</strong> number[] | number<br />
|
|
336
|
+
<br />
|
|
337
|
+
<strong>Description:</strong> <em><br />
|
|
338
|
+
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 />
|
|
339
|
+
<br />
|
|
340
|
+
⚠ Note:<br />
|
|
341
|
+
The values are specified following the <code>horizontal/vertical</code> rule in pixels, regardless of the <code>direction</code>.</em><br />
|
|
342
|
+
<br />
|
|
343
|
+
<strong>Example:</strong>
|
|
344
|
+
|
|
345
|
+
```tsx
|
|
346
|
+
<MorphScroll
|
|
347
|
+
gap={10}
|
|
348
|
+
// gap={[10, 10]}
|
|
349
|
+
// another props
|
|
350
|
+
>
|
|
351
|
+
{children}
|
|
352
|
+
</MorphScroll>
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
</ul>
|
|
160
356
|
</details>
|
|
161
|
-
<h2>
|
|
162
357
|
|
|
163
|
-
|
|
358
|
+
##
|
|
359
|
+
|
|
164
360
|
<details>
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
361
|
+
<summary><strong><code>padding</code></strong> : <em>Padding for the <code>objectsWrapper</code>.</em></summary><br />
|
|
362
|
+
<ul>
|
|
363
|
+
<strong>Type:</strong> number[] | number<br />
|
|
364
|
+
<br />
|
|
365
|
+
<strong>Description:</strong> <em><br />
|
|
366
|
+
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 />
|
|
367
|
+
<br />
|
|
368
|
+
⚠ Note:<br />
|
|
369
|
+
<ul>
|
|
370
|
+
<li>
|
|
371
|
+
This parameter accepts either a single number or an array of numbers
|
|
372
|
+
<ul>
|
|
373
|
+
<li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
|
|
374
|
+
<li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
|
|
375
|
+
</ul>
|
|
376
|
+
</li>
|
|
377
|
+
<li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
|
|
378
|
+
<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>
|
|
379
|
+
</ul></em><br />
|
|
380
|
+
<br />
|
|
381
|
+
<strong>Example:</strong>
|
|
382
|
+
|
|
383
|
+
```tsx
|
|
384
|
+
<MorphScroll
|
|
385
|
+
padding={10}
|
|
386
|
+
// padding={[10, 10]}
|
|
387
|
+
// padding={[10, 10, 10, 10]}
|
|
388
|
+
// another props
|
|
389
|
+
>
|
|
390
|
+
{children}
|
|
391
|
+
</MorphScroll>
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
</ul>
|
|
395
|
+
</details>
|
|
175
396
|
|
|
176
|
-
|
|
177
|
-
<MorphScroll
|
|
178
|
-
stopLoadOnScroll
|
|
179
|
-
// another props
|
|
180
|
-
>
|
|
181
|
-
{children}
|
|
182
|
-
</MorphScroll>
|
|
183
|
-
```
|
|
397
|
+
##
|
|
184
398
|
|
|
399
|
+
<details>
|
|
400
|
+
<summary><strong><code>contentAlign</code></strong> : <em>Aligns the content when it is smaller than the MorphScroll <code>size</code>.</em></summary><br />
|
|
401
|
+
<ul>
|
|
402
|
+
<strong>Type:</strong> [<br />
|
|
403
|
+
"start" | "center" | "end",<br />
|
|
404
|
+
"start" | "center" | "end"<br />
|
|
405
|
+
]<br />
|
|
406
|
+
<strong>Description:</strong> <em><br />
|
|
407
|
+
This parameter aligns the `objectsWrapper`, which contains all the provided elements, relative to the scroll or the `size`.<br />
|
|
408
|
+
<br />
|
|
409
|
+
⚠ Note:<br />
|
|
410
|
+
<ul>
|
|
411
|
+
<li>Only takes effect when `objectsWrapper` is smaller than the scroll container.
|
|
412
|
+
</li>
|
|
413
|
+
<li>The values are specified following the horizontal/vertical rule, regardless of the direction.
|
|
414
|
+
</li>
|
|
415
|
+
</ul></em><br />
|
|
416
|
+
<br />
|
|
417
|
+
<strong>Example:</strong>
|
|
418
|
+
|
|
419
|
+
```tsx
|
|
420
|
+
<MorphScroll
|
|
421
|
+
contentAlign={["center", "center"]}
|
|
422
|
+
// another props
|
|
423
|
+
>
|
|
424
|
+
{children}
|
|
425
|
+
</MorphScroll>
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
</ul>
|
|
185
429
|
</details>
|
|
186
|
-
<h2>
|
|
187
430
|
|
|
188
|
-
|
|
431
|
+
##
|
|
432
|
+
|
|
189
433
|
<details>
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
434
|
+
<summary><strong><code>elementsAlign</code></strong> : <em>Aligns the objects within the <code>objectsWrapper</code>.</em></summary><br />
|
|
435
|
+
<ul>
|
|
436
|
+
<strong>Type:</strong> "start" | "center" | "end"<br />
|
|
437
|
+
<br />
|
|
438
|
+
<strong>Example:</strong>
|
|
439
|
+
|
|
440
|
+
```tsx
|
|
441
|
+
<MorphScroll
|
|
442
|
+
elementsAlign="center"
|
|
443
|
+
// another props
|
|
444
|
+
>
|
|
445
|
+
{children}
|
|
446
|
+
</MorphScroll>
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
</ul>
|
|
450
|
+
</details>
|
|
198
451
|
|
|
199
|
-
|
|
200
|
-
<MorphScroll
|
|
201
|
-
onScrollValue={
|
|
202
|
-
(scroll) => {
|
|
203
|
-
console.log("Scroll position:", scroll);
|
|
204
|
-
return scroll > 100;
|
|
205
|
-
},
|
|
206
|
-
}
|
|
207
|
-
// another props
|
|
208
|
-
>
|
|
209
|
-
{children}
|
|
210
|
-
</MorphScroll>
|
|
211
|
-
```
|
|
452
|
+
##
|
|
212
453
|
|
|
454
|
+
<details>
|
|
455
|
+
<summary><strong><code>edgeGradient</code></strong> : <em>Gradient when scrolling overflows.</em></summary><br />
|
|
456
|
+
<ul>
|
|
457
|
+
<strong>Type:</strong> boolean | { color?: string; size?: number }<br />
|
|
458
|
+
<br />
|
|
459
|
+
<strong>Default:</strong> When using true or color, the default size will be 40<br />
|
|
460
|
+
<br />
|
|
461
|
+
<strong>Description:</strong> <em><br />
|
|
462
|
+
This parameter creates two edge elements responsible for darkening the edges of the scroll when it overflows.<br />
|
|
463
|
+
<br />
|
|
464
|
+
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 />
|
|
465
|
+
<br />
|
|
466
|
+
⚠ Note:<br />
|
|
467
|
+
The size property, measured in pixels, adjusts the dimensions of the edge elements.</em><br />
|
|
468
|
+
<br />
|
|
469
|
+
<strong>Example:</strong>
|
|
470
|
+
|
|
471
|
+
```tsx
|
|
472
|
+
<MorphScroll
|
|
473
|
+
edgeGradient={{ color: "rgba(0, 0, 0, 0.5)" }}
|
|
474
|
+
// edgeGradient={{ color: "rgba(0, 0, 0, 0.5)", size: 20 }}
|
|
475
|
+
// edgeGradient
|
|
476
|
+
// another props
|
|
477
|
+
>
|
|
478
|
+
{children}
|
|
479
|
+
</MorphScroll>
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
</ul>
|
|
213
483
|
</details>
|
|
214
|
-
<h2>
|
|
215
484
|
|
|
216
|
-
|
|
485
|
+
##
|
|
486
|
+
|
|
217
487
|
<details>
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
488
|
+
<summary><strong><code>progressReverse</code></strong> : <em>Reverse the progress bar position.</em></summary><br />
|
|
489
|
+
<ul>
|
|
490
|
+
<strong>Type:</strong> boolean<br />
|
|
491
|
+
<br />
|
|
492
|
+
<strong>Default:</strong> false<br />
|
|
493
|
+
<br />
|
|
494
|
+
<strong>Description:</strong> <em><br />
|
|
495
|
+
This parameter changes the position of the progress bar based on the direction property.<br />
|
|
496
|
+
<ul>
|
|
497
|
+
<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>
|
|
498
|
+
<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>
|
|
499
|
+
</ul></em><br />
|
|
500
|
+
<br />
|
|
501
|
+
<strong>Example:</strong>
|
|
502
|
+
|
|
503
|
+
```tsx
|
|
504
|
+
<MorphScroll
|
|
505
|
+
progressReverse
|
|
506
|
+
// another props
|
|
507
|
+
>
|
|
508
|
+
{children}
|
|
509
|
+
</MorphScroll>
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
</ul>
|
|
513
|
+
</details>
|
|
226
514
|
|
|
227
|
-
|
|
228
|
-
<MorphScroll
|
|
229
|
-
isScrolling={(motion) => {
|
|
230
|
-
console.log(motion ? "Scrolling..." : "Scroll stopped.");
|
|
231
|
-
}}
|
|
232
|
-
// another props
|
|
233
|
-
>
|
|
234
|
-
{children}
|
|
235
|
-
</MorphScroll>
|
|
236
|
-
```
|
|
515
|
+
##
|
|
237
516
|
|
|
517
|
+
<details>
|
|
518
|
+
<summary><strong><code>progressVisibility</code></strong> : <em>Visibility of the progress bar.</em></summary><br />
|
|
519
|
+
<ul>
|
|
520
|
+
<strong>Type:</strong> "visible" | "hover" | "hidden"<br />
|
|
521
|
+
<br />
|
|
522
|
+
<strong>Default:</strong> "visible"<br />
|
|
523
|
+
<br />
|
|
524
|
+
<strong>Description:</strong> <em><br />
|
|
525
|
+
This parameter controls the visibility of the progress bar regardless of the <code>type</code> value.</em><br />
|
|
526
|
+
<br />
|
|
527
|
+
<strong>Example:</strong>
|
|
528
|
+
|
|
529
|
+
```tsx
|
|
530
|
+
<MorphScroll
|
|
531
|
+
progressVisibility="hover"
|
|
532
|
+
// another props
|
|
533
|
+
>
|
|
534
|
+
{children}
|
|
535
|
+
</MorphScroll>
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
</ul>
|
|
238
539
|
</details>
|
|
239
540
|
|
|
240
|
-
|
|
541
|
+
##
|
|
241
542
|
|
|
242
|
-
- **`size`:** _MorphScroll width and height._
|
|
243
543
|
<details>
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
544
|
+
<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 />
|
|
545
|
+
<ul>
|
|
546
|
+
<strong>Type:</strong> boolean<br /><br />
|
|
547
|
+
<strong>Default:</strong> false<br /><br />
|
|
548
|
+
<strong>Description:</strong> <em><br />
|
|
549
|
+
In process of development</em><br />
|
|
550
|
+
<br />
|
|
551
|
+
<strong>Example:</strong>
|
|
552
|
+
|
|
553
|
+
```tsx
|
|
554
|
+
<MorphScroll
|
|
555
|
+
objectsWrapFullMinSize
|
|
556
|
+
// another props
|
|
557
|
+
>
|
|
558
|
+
{children}
|
|
559
|
+
</MorphScroll>
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
</ul>
|
|
563
|
+
</details>
|
|
256
564
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
// another props
|
|
261
|
-
>
|
|
262
|
-
{children}
|
|
263
|
-
</MorphScroll>
|
|
264
|
-
```
|
|
565
|
+
##
|
|
566
|
+
|
|
567
|
+
#### PROGRESS AND RENDERING:
|
|
265
568
|
|
|
569
|
+
<details>
|
|
570
|
+
<summary><strong><code>progressTrigger</code></strong> : <em>Triggers for the progress bar.</em></summary><br />
|
|
571
|
+
<ul>
|
|
572
|
+
<strong>Type:</strong> {<br />
|
|
573
|
+
wheel?: boolean;<br />
|
|
574
|
+
content?: boolean;<br />
|
|
575
|
+
progressElement?: boolean | React.ReactNode;<br />
|
|
576
|
+
arrows?: boolean | { size?: number; element?: React.ReactNode };<br />
|
|
577
|
+
}<br />
|
|
578
|
+
<br />
|
|
579
|
+
<strong>Default:</strong> { wheel: true }<br />
|
|
580
|
+
<br />
|
|
581
|
+
<strong>Description:</strong> <em><br />
|
|
582
|
+
This is one of the most important parameters, allowing you to define how users interact with the progress bar and customize its appearance.<br />
|
|
583
|
+
<br />
|
|
584
|
+
<ul>
|
|
585
|
+
<li>The <code>wheel</code> property determines whether the progress bar responds to mouse wheel scrolling.</li>
|
|
586
|
+
<li>The <code>content</code> property enables interaction by clicking and dragging anywhere within the scrollable content to move it.</li>
|
|
587
|
+
<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>
|
|
588
|
+
<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>
|
|
589
|
+
</ul></em><br />
|
|
590
|
+
<br />
|
|
591
|
+
<strong>Example:</strong>
|
|
592
|
+
|
|
593
|
+
```tsx
|
|
594
|
+
<MorphScroll
|
|
595
|
+
progressTrigger={{
|
|
596
|
+
wheel: true,
|
|
597
|
+
progressElement: <div className="your-scroll-thumb" />,
|
|
598
|
+
}}
|
|
599
|
+
// another props
|
|
600
|
+
>
|
|
601
|
+
{children}
|
|
602
|
+
</MorphScroll>
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
</ul>
|
|
266
606
|
</details>
|
|
267
|
-
<h2>
|
|
268
607
|
|
|
269
|
-
|
|
608
|
+
##
|
|
609
|
+
|
|
270
610
|
<details>
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
611
|
+
<summary><strong><code>render</code></strong> : <em>Types of rendering for optimization.</em></summary><br />
|
|
612
|
+
<ul>
|
|
613
|
+
<strong>Type:</strong><br />
|
|
614
|
+
| { type: "default" }<br />
|
|
615
|
+
| { type: "lazy"; rootMargin?: number | number[]; onVisible?: (key: string) => void }<br />
|
|
616
|
+
| { type: "virtual"; rootMargin?: number | number[] }<br />
|
|
617
|
+
<br />
|
|
618
|
+
<strong>Default:</strong> { type: "default" }<br />
|
|
619
|
+
<br />
|
|
620
|
+
<strong>Description:</strong> <em><br />
|
|
621
|
+
This parameter defines the rendering type for optimization.<br />
|
|
622
|
+
<br />
|
|
623
|
+
<ul>
|
|
624
|
+
<li>With <code>default</code>, no optimizations are applied.</li>
|
|
625
|
+
<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>
|
|
626
|
+
<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>
|
|
627
|
+
</ul><br />
|
|
628
|
+
<br />
|
|
629
|
+
⚠ Note:<br />
|
|
630
|
+
<ul>
|
|
631
|
+
<li>The <code>onVisible</code> property is the same as in <code>IntersectionTracker/onVisible</code>.</li>
|
|
632
|
+
<li>
|
|
633
|
+
The <code>rootMargin</code> property accepts either a single number or an array of numbers.
|
|
634
|
+
<ul>
|
|
635
|
+
<li>If a two-number array is provided, the values follow the <code>horizontal/vertical</code> rule.</li>
|
|
636
|
+
<li>If a four-number array is provided, the values follow the <code>top/right/bottom/left</code> rule.</li>
|
|
637
|
+
</ul>
|
|
638
|
+
</li>
|
|
639
|
+
<li>All values are in pixels and apply regardless of the <code>direction</code>.</li>
|
|
640
|
+
</ul></em><br />
|
|
641
|
+
<br />
|
|
642
|
+
<strong>Example:</strong>
|
|
643
|
+
|
|
644
|
+
```tsx
|
|
645
|
+
<MorphScroll
|
|
646
|
+
render={{ type: "virtual" }}
|
|
647
|
+
// render={{
|
|
648
|
+
// type: "lazy",
|
|
649
|
+
// rootMargin: [0, 100],
|
|
650
|
+
// onVisible: () => console.log("visible"))
|
|
651
|
+
// }}
|
|
652
|
+
// another props
|
|
653
|
+
>
|
|
654
|
+
{children}
|
|
655
|
+
</MorphScroll>
|
|
656
|
+
```
|
|
657
|
+
|
|
658
|
+
</ul>
|
|
659
|
+
</details>
|
|
284
660
|
|
|
285
|
-
|
|
286
|
-
<MorphScroll
|
|
287
|
-
objectsSize={[40, 40]}
|
|
288
|
-
// objectsSize={["none", "none"]}
|
|
289
|
-
// objectsSize={["firstChild", "firstChild"]}
|
|
290
|
-
// another props
|
|
291
|
-
>
|
|
292
|
-
{children}
|
|
293
|
-
</MorphScroll>
|
|
294
|
-
```
|
|
661
|
+
##
|
|
295
662
|
|
|
663
|
+
<details>
|
|
664
|
+
<summary><strong><code>emptyElements</code></strong> : <em>Handling of empty scroll elements.</em></summary><br />
|
|
665
|
+
<ul>
|
|
666
|
+
<strong>Type:</strong><br />
|
|
667
|
+
| {
|
|
668
|
+
mode: "clear";
|
|
669
|
+
clickTrigger?: { selector: string; delay?: number };
|
|
670
|
+
}<br />
|
|
671
|
+
| {
|
|
672
|
+
mode: "fallback";
|
|
673
|
+
element?: React.ReactNode;
|
|
674
|
+
clickTrigger?: { selector: string; delay?: number };
|
|
675
|
+
}<br /><br />
|
|
676
|
+
<strong>Description:</strong> <em><br />
|
|
677
|
+
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 />
|
|
678
|
+
<br />
|
|
679
|
+
<ul>
|
|
680
|
+
<li><code>mode: "clear"</code> – automatically removes empty elements, eliminating unnecessary gaps in the scroll list.</li>
|
|
681
|
+
<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>
|
|
682
|
+
</ul><br />
|
|
683
|
+
<br />
|
|
684
|
+
<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 />
|
|
685
|
+
<br />
|
|
686
|
+
⚠ Note:<br />
|
|
687
|
+
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 />
|
|
688
|
+
<br />
|
|
689
|
+
<strong>Example:</strong>
|
|
690
|
+
|
|
691
|
+
```tsx
|
|
692
|
+
<MorphScroll
|
|
693
|
+
emptyElements={{
|
|
694
|
+
mode: "clear",
|
|
695
|
+
clickTrigger: { selector: ".close-button" },
|
|
696
|
+
}}
|
|
697
|
+
// emptyElements={{
|
|
698
|
+
// mode: "fallback",
|
|
699
|
+
// clickTrigger: {
|
|
700
|
+
// selector: ".close-button",
|
|
701
|
+
// delay: 100,
|
|
702
|
+
// },
|
|
703
|
+
// }}
|
|
704
|
+
// another props
|
|
705
|
+
>
|
|
706
|
+
{children}
|
|
707
|
+
</MorphScroll>
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
</ul>
|
|
296
711
|
</details>
|
|
297
|
-
<h2>
|
|
298
712
|
|
|
299
|
-
|
|
713
|
+
##
|
|
714
|
+
|
|
300
715
|
<details>
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
716
|
+
<summary><strong><code>suspending</code></strong> : <em>Adds React Suspense.</em></summary><br />
|
|
717
|
+
<ul>
|
|
718
|
+
<strong>Type:</strong> boolean<br />
|
|
719
|
+
<br />
|
|
720
|
+
<strong>Default:</strong> false<br />
|
|
721
|
+
<br />
|
|
722
|
+
<strong>Description:</strong> <em><br />
|
|
723
|
+
This parameter adds React Suspense to the MorphScroll component for asynchronous rendering.</em><br />
|
|
724
|
+
<br />
|
|
725
|
+
<strong>Example:</strong>
|
|
310
726
|
|
|
311
727
|
```tsx
|
|
312
728
|
<MorphScroll
|
|
313
|
-
|
|
314
|
-
// gap={[10, 10]}
|
|
729
|
+
suspending
|
|
315
730
|
// another props
|
|
316
731
|
>
|
|
317
732
|
{children}
|
|
318
733
|
</MorphScroll>
|
|
319
734
|
```
|
|
320
735
|
|
|
736
|
+
</ul>
|
|
321
737
|
</details>
|
|
322
|
-
<h2>
|
|
323
738
|
|
|
324
|
-
|
|
739
|
+
##
|
|
740
|
+
|
|
325
741
|
<details>
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
<br />
|
|
335
|
-
*Important: 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.</em><br />
|
|
336
|
-
<br />
|
|
337
|
-
<strong>• Example:</strong>
|
|
742
|
+
<summary><strong><code>fallback</code></strong> : <em>Fallback element.</em></summary><br />
|
|
743
|
+
<ul>
|
|
744
|
+
<strong>Type:</strong> React.ReactNode<br />
|
|
745
|
+
<br />
|
|
746
|
+
<strong>Description:</strong> <em><br />
|
|
747
|
+
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 />
|
|
748
|
+
<br />
|
|
749
|
+
<strong>Example:</strong>
|
|
338
750
|
|
|
339
751
|
```tsx
|
|
340
752
|
<MorphScroll
|
|
341
|
-
|
|
342
|
-
// padding={[10, 10]}
|
|
343
|
-
// padding={[10, 10, 10, 10]}
|
|
753
|
+
fallback={<div>Loading...</div>}
|
|
344
754
|
// another props
|
|
345
755
|
>
|
|
346
756
|
{children}
|
|
347
757
|
</MorphScroll>
|
|
348
758
|
```
|
|
349
759
|
|
|
760
|
+
</ul>
|
|
350
761
|
</details>
|
|
351
|
-
<h2>
|
|
352
762
|
|
|
353
|
-
|
|
763
|
+
##
|
|
764
|
+
|
|
765
|
+
### 〈♦ ResizeTracker 〉
|
|
766
|
+
|
|
767
|
+
`ResizeTracker` is a React component that monitors changes to an element’s size. It provides updated dimensions via a render-prop function whenever the observed element is resized.
|
|
768
|
+
|
|
769
|
+
- ### Props:
|
|
770
|
+
|
|
354
771
|
<details>
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
772
|
+
<summary><strong><code>children</code></strong> : <em>Render-prop function for size updates and adding content.</em></summary><br />
|
|
773
|
+
<ul>
|
|
774
|
+
<strong>Type:</strong> (rect: DOMRectReadOnly) => React.ReactNode<br />
|
|
775
|
+
<br />
|
|
776
|
+
<strong>Description:</strong> <em><br />
|
|
777
|
+
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 />
|
|
778
|
+
<br />
|
|
779
|
+
The function receives an object of type <code>DOMRectReadOnly</code> with the following properties:
|
|
780
|
+
<ul>
|
|
781
|
+
<li><code>x</code> - The X-coordinate of the top-left corner of the element.</li>
|
|
782
|
+
<li><code>y</code> - The Y-coordinate of the top-left corner of the element.</li>
|
|
783
|
+
<li><code>width</code> - The width of the observed element’s content box.</li>
|
|
784
|
+
<li><code>height</code> - The height of the observed element’s content box.</li>
|
|
785
|
+
<li><code>top</code> - The distance from the top of the element to its parent's top. Equal to <code>y</code>.</li>
|
|
786
|
+
<li><code>left</code> - The distance from the left of the element to its parent's left. Equal to <code>x</code>.</li>
|
|
787
|
+
<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>
|
|
788
|
+
<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>
|
|
789
|
+
</ul><br />
|
|
790
|
+
<br />
|
|
791
|
+
⚠ 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 />
|
|
792
|
+
<br />
|
|
793
|
+
<strong>Example:</strong>
|
|
363
794
|
|
|
364
795
|
```tsx
|
|
365
|
-
<
|
|
796
|
+
<ResizeTracker
|
|
366
797
|
// another props
|
|
367
798
|
>
|
|
368
|
-
{
|
|
369
|
-
|
|
799
|
+
{(rect) => (
|
|
800
|
+
<p>
|
|
801
|
+
Width: {rect.width}, Height: {rect.height}
|
|
802
|
+
</p>
|
|
803
|
+
)}
|
|
804
|
+
</ResizeTracker>
|
|
370
805
|
```
|
|
371
806
|
|
|
807
|
+
</ul>
|
|
808
|
+
|
|
372
809
|
</details>
|
|
373
|
-
<h2>
|
|
374
810
|
|
|
375
|
-
|
|
811
|
+
##
|
|
812
|
+
|
|
376
813
|
<details>
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
.</em><br />
|
|
383
|
-
<br />
|
|
384
|
-
<strong>• Example:</strong>
|
|
814
|
+
<summary><strong><code>style</code></strong> : <em>Applies inline styles to the container.</em></summary><br />
|
|
815
|
+
<ul>
|
|
816
|
+
<strong>Type:</strong> React.CSSProperties<br />
|
|
817
|
+
<br />
|
|
818
|
+
<strong>Example:</strong>
|
|
385
819
|
|
|
386
820
|
```tsx
|
|
387
|
-
<
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
</
|
|
821
|
+
<ResizeTracker style={{ backgroundColor: "blue" }}>
|
|
822
|
+
{(rect) => (
|
|
823
|
+
// content
|
|
824
|
+
)}
|
|
825
|
+
</ResizeTracker>
|
|
392
826
|
```
|
|
393
827
|
|
|
828
|
+
</ul>
|
|
829
|
+
|
|
394
830
|
</details>
|
|
395
|
-
<h2>
|
|
396
831
|
|
|
397
|
-
|
|
832
|
+
##
|
|
833
|
+
|
|
398
834
|
<details>
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
835
|
+
<summary><strong><code>measure</code></strong> : <em>Defines the measurement strategy.</em></summary><br />
|
|
836
|
+
<ul>
|
|
837
|
+
<strong>Type:</strong> "inner" | "outer" | "all"<br />
|
|
838
|
+
<br />
|
|
839
|
+
<strong>Default:</strong> "inner"<br />
|
|
840
|
+
<br />
|
|
841
|
+
<strong>Description:</strong><br />
|
|
842
|
+
<em>This prop determines what is being measured by automatically applying inline styles that affect width and height.<br />
|
|
843
|
+
<br />
|
|
844
|
+
- 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 />
|
|
845
|
+
- The <code>"outer"</code> value measures the parent element by setting <code>minWidth: "100%"</code> and <code>minHeight: "100%"</code>.<br />
|
|
846
|
+
- 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 />
|
|
847
|
+
<br />
|
|
848
|
+
⚠ 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 />
|
|
849
|
+
<br />
|
|
850
|
+
<strong>Example:</strong>
|
|
409
851
|
|
|
410
852
|
```tsx
|
|
411
|
-
<
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
</
|
|
853
|
+
<ResizeTracker measure="all">
|
|
854
|
+
{(rect) => (
|
|
855
|
+
// content
|
|
856
|
+
)}
|
|
857
|
+
</ResizeTracker>
|
|
416
858
|
```
|
|
417
859
|
|
|
860
|
+
</ul>
|
|
861
|
+
|
|
418
862
|
</details>
|
|
419
|
-
<h2>
|
|
420
863
|
|
|
421
|
-
|
|
864
|
+
##
|
|
865
|
+
|
|
422
866
|
<details>
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
<strong>• Example:</strong>
|
|
867
|
+
<summary><strong><code>onResize</code></strong> : <em>Callback triggered on size changes.</em></summary><br />
|
|
868
|
+
<ul>
|
|
869
|
+
<strong>Type:</strong> (rect: Partial<DOMRectReadOnly>) => void<br />
|
|
870
|
+
<br />
|
|
871
|
+
<strong>Description:</strong><br />
|
|
872
|
+
<em>A callback function that is triggered whenever the observed element's dimensions change.<br />
|
|
873
|
+
The function receives an object containing the updated size properties.</em><br />
|
|
874
|
+
<br />
|
|
875
|
+
<strong>Example:</strong>
|
|
433
876
|
|
|
434
877
|
```tsx
|
|
435
|
-
<
|
|
436
|
-
|
|
878
|
+
<ResizeTracker
|
|
879
|
+
onResize={(rect) => {
|
|
880
|
+
console.log("New size:", rect);
|
|
881
|
+
}}
|
|
437
882
|
>
|
|
438
|
-
{
|
|
439
|
-
|
|
883
|
+
{(rect) => (
|
|
884
|
+
// content
|
|
885
|
+
)}
|
|
886
|
+
</ResizeTracker>
|
|
440
887
|
```
|
|
441
888
|
|
|
889
|
+
</ul>
|
|
890
|
+
|
|
442
891
|
</details>
|
|
443
|
-
<h2>
|
|
444
892
|
|
|
445
|
-
|
|
893
|
+
##
|
|
894
|
+
|
|
895
|
+
- ### Link:
|
|
896
|
+
|
|
897
|
+
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
|
|
898
|
+
|
|
899
|
+
##
|
|
900
|
+
|
|
901
|
+
### 〈♦ IntersectionTracker 〉
|
|
902
|
+
|
|
903
|
+
`IntersectionTracker` is a React component for tracking the intersection of an element with the viewport.
|
|
904
|
+
|
|
905
|
+
- ### Props:
|
|
906
|
+
|
|
446
907
|
<details>
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
<br />
|
|
453
|
-
<strong>• Description:</strong> <em><br />
|
|
454
|
-
.</em><br />
|
|
455
|
-
<br />
|
|
456
|
-
<strong>• Example:</strong>
|
|
908
|
+
<summary><strong><code>children</code></strong> : <em>Custom user content.</em></summary><br />
|
|
909
|
+
<ul>
|
|
910
|
+
<strong>Type:</strong> React.ReactNode<br />
|
|
911
|
+
<br />
|
|
912
|
+
<strong>Example:</strong>
|
|
457
913
|
|
|
458
914
|
```tsx
|
|
459
|
-
<
|
|
460
|
-
// another props
|
|
461
|
-
>
|
|
462
|
-
{children}
|
|
463
|
-
</MorphScroll>
|
|
915
|
+
<IntersectionTracker>{children}</IntersectionTracker>
|
|
464
916
|
```
|
|
465
917
|
|
|
918
|
+
</ul>
|
|
919
|
+
|
|
466
920
|
</details>
|
|
467
|
-
<h2>
|
|
468
921
|
|
|
469
|
-
|
|
922
|
+
##
|
|
923
|
+
|
|
470
924
|
<details>
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
<br />
|
|
477
|
-
<strong>• Description:</strong> <em><br />
|
|
478
|
-
.</em><br />
|
|
479
|
-
<br />
|
|
480
|
-
<strong>• Example:</strong>
|
|
925
|
+
<summary><strong><code>style</code></strong> : <em>Applies inline styles to the container.</em></summary><br />
|
|
926
|
+
<ul>
|
|
927
|
+
<strong>Type:</strong> React.CSSProperties<br />
|
|
928
|
+
<br />
|
|
929
|
+
<strong>Example:</strong>
|
|
481
930
|
|
|
482
931
|
```tsx
|
|
483
|
-
<
|
|
484
|
-
// another props
|
|
485
|
-
>
|
|
932
|
+
<IntersectionTracker style={{ backgroundColor: "blue" }}>
|
|
486
933
|
{children}
|
|
487
|
-
</
|
|
934
|
+
</IntersectionTracker>
|
|
488
935
|
```
|
|
489
936
|
|
|
937
|
+
</ul>
|
|
938
|
+
|
|
490
939
|
</details>
|
|
491
940
|
|
|
492
|
-
|
|
941
|
+
##
|
|
493
942
|
|
|
494
|
-
- **`progressTrigger`:** _Triggers for the progress bar._
|
|
495
943
|
<details>
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
<br />
|
|
510
|
-
<strong>• Example:</strong>
|
|
944
|
+
<summary><strong><code>root</code></strong> : <em>Defines the observation area.</em></summary><br />
|
|
945
|
+
<ul>
|
|
946
|
+
<strong>Type:</strong> Element | null<br />
|
|
947
|
+
<br />
|
|
948
|
+
<strong>Default:</strong> null (window)<br />
|
|
949
|
+
<br />
|
|
950
|
+
<strong>Description:</strong> <em><br />
|
|
951
|
+
Specifies the element that serves as the bounding box for the intersection observation.
|
|
952
|
+
If provided, it must be an ancestor of the observed element.<br />
|
|
953
|
+
<br />
|
|
954
|
+
If set to <code>null</code> (default), the window is used as the observation area.</em><br />
|
|
955
|
+
<br />
|
|
956
|
+
<strong>Example:</strong>
|
|
511
957
|
|
|
512
958
|
```tsx
|
|
513
|
-
<
|
|
514
|
-
// another props
|
|
515
|
-
>
|
|
959
|
+
<IntersectionTracker root={document.getElementById("root")}>
|
|
516
960
|
{children}
|
|
517
|
-
</
|
|
961
|
+
</IntersectionTracker>
|
|
518
962
|
```
|
|
519
963
|
|
|
964
|
+
</ul>
|
|
965
|
+
|
|
520
966
|
</details>
|
|
521
|
-
<h2>
|
|
522
967
|
|
|
523
|
-
|
|
968
|
+
##
|
|
969
|
+
|
|
524
970
|
<details>
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
971
|
+
<summary><strong><code>rootMargin</code></strong> : <em>Sets the margin around the root element.</em></summary><br />
|
|
972
|
+
<ul>
|
|
973
|
+
<strong>Type:</strong> number | number[]<br />
|
|
974
|
+
<br />
|
|
975
|
+
<strong>Description:</strong> <em><br />
|
|
976
|
+
Defines an offset around the root element, expanding or shrinking the observed area.<br />
|
|
977
|
+
<br />
|
|
978
|
+
Accepts a single number or an array for fine-tuned control:<br />
|
|
979
|
+
<ul>
|
|
980
|
+
<li>A <strong>single number</strong> sets the same margin on all sides.</li>
|
|
981
|
+
<li>A <strong>two-value array</strong> <code>[topBottom, leftRight]</code> applies margins vertically and horizontally.</li>
|
|
982
|
+
<li>A <strong>four-value array</strong> <code>[top, right, bottom, left]</code> allows full control over each side.</li>
|
|
983
|
+
</ul>
|
|
984
|
+
<br />
|
|
985
|
+
Margins are converted to <code>px</code> values internally.</em><br />
|
|
986
|
+
<br />
|
|
987
|
+
<strong>Example:</strong>
|
|
538
988
|
|
|
539
989
|
```tsx
|
|
540
|
-
<
|
|
541
|
-
|
|
990
|
+
<IntersectionTracker
|
|
991
|
+
rootMargin={10}
|
|
992
|
+
// rootMargin={[10, 20]}
|
|
993
|
+
// rootMargin={[10, 20, 10, 20]}
|
|
542
994
|
>
|
|
543
995
|
{children}
|
|
544
|
-
</
|
|
996
|
+
</IntersectionTracker>
|
|
545
997
|
```
|
|
546
998
|
|
|
999
|
+
</ul>
|
|
1000
|
+
|
|
547
1001
|
</details>
|
|
548
|
-
<h2>
|
|
549
1002
|
|
|
550
|
-
|
|
1003
|
+
##
|
|
1004
|
+
|
|
551
1005
|
<details>
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
<strong>• Description:</strong> <em><br />
|
|
568
|
-
.</em><br />
|
|
569
|
-
<br />
|
|
570
|
-
<strong>• Example:</strong>
|
|
1006
|
+
<summary><strong><code>threshold</code></strong> : <em>Defines when the callback is triggered.</em></summary><br />
|
|
1007
|
+
<ul>
|
|
1008
|
+
<strong>Type:</strong> number | number[]<br />
|
|
1009
|
+
<br />
|
|
1010
|
+
<strong>Description:</strong> <em><br />
|
|
1011
|
+
.Specifies at what percentage of the observed element’s visibility the callback should be executed.<br />
|
|
1012
|
+
<br />
|
|
1013
|
+
<ul>
|
|
1014
|
+
<li>A <strong>single number</strong> (e.g., <code>0.5</code>) triggers when that fraction of the element is visible.</li>
|
|
1015
|
+
<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>
|
|
1016
|
+
</ul>
|
|
1017
|
+
<br />
|
|
1018
|
+
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 />
|
|
1019
|
+
<br />
|
|
1020
|
+
<strong>Example:</strong>
|
|
571
1021
|
|
|
572
1022
|
```tsx
|
|
573
|
-
<
|
|
574
|
-
|
|
1023
|
+
<IntersectionTracker
|
|
1024
|
+
threshold={0.5}
|
|
1025
|
+
// threshold={[0, 0.5, 1]}
|
|
575
1026
|
>
|
|
576
1027
|
{children}
|
|
577
|
-
</
|
|
1028
|
+
</IntersectionTracker>
|
|
578
1029
|
```
|
|
579
1030
|
|
|
1031
|
+
</ul>
|
|
1032
|
+
|
|
580
1033
|
</details>
|
|
581
|
-
<h2>
|
|
582
1034
|
|
|
583
|
-
|
|
1035
|
+
##
|
|
1036
|
+
|
|
584
1037
|
<details>
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
1038
|
+
<summary><strong><code>visibleContent</code></strong> : <em>Makes all elements always visible.</em></summary><br />
|
|
1039
|
+
<ul>
|
|
1040
|
+
<strong>Type:</strong> boolean<br />
|
|
1041
|
+
<br />
|
|
1042
|
+
<strong>Default:</strong> false<br />
|
|
1043
|
+
<br />
|
|
1044
|
+
<strong>Description:</strong> <em><br />
|
|
1045
|
+
If set to `true`, the tracked elements will always be visible, regardless of their actual intersection status.
|
|
1046
|
+
<br />
|
|
1047
|
+
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 />
|
|
1048
|
+
<br />
|
|
1049
|
+
<strong>Example:</strong>
|
|
595
1050
|
|
|
596
1051
|
```tsx
|
|
597
|
-
<
|
|
598
|
-
// another props
|
|
599
|
-
>
|
|
600
|
-
{children}
|
|
601
|
-
</MorphScroll>
|
|
1052
|
+
<IntersectionTracker visibleContent>{children}</IntersectionTracker>
|
|
602
1053
|
```
|
|
603
1054
|
|
|
1055
|
+
</ul>
|
|
1056
|
+
|
|
604
1057
|
</details>
|
|
605
|
-
<h2>
|
|
606
1058
|
|
|
607
|
-
|
|
1059
|
+
##
|
|
1060
|
+
|
|
608
1061
|
<details>
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
1062
|
+
<summary><strong><code>onVisible</code></strong> : <em>Callback function triggered when the element becomes visible.</em></summary><br />
|
|
1063
|
+
<ul>
|
|
1064
|
+
<strong>Type:</strong> (key: string) => void<br />
|
|
1065
|
+
<br />
|
|
1066
|
+
<strong>Description:</strong> <em><br />
|
|
1067
|
+
A callback function that is invoked when the observed element enters the viewport or the defined observation area.<br />
|
|
1068
|
+
<br />
|
|
1069
|
+
The callback receives the <code>key</code> of the first child element as a parameter.<br />
|
|
1070
|
+
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 />
|
|
1071
|
+
<br />
|
|
1072
|
+
⚠ Note:<br />
|
|
1073
|
+
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 />
|
|
1074
|
+
<br />
|
|
1075
|
+
<strong>Example:</strong>
|
|
617
1076
|
|
|
618
1077
|
```tsx
|
|
619
|
-
<
|
|
620
|
-
|
|
1078
|
+
<IntersectionTracker
|
|
1079
|
+
onVisible={(key) => {
|
|
1080
|
+
if (key.includes("elementId")) {
|
|
1081
|
+
// do something
|
|
1082
|
+
}
|
|
1083
|
+
}}
|
|
621
1084
|
>
|
|
622
1085
|
{children}
|
|
623
|
-
</
|
|
1086
|
+
</IntersectionTracker>
|
|
624
1087
|
```
|
|
625
1088
|
|
|
1089
|
+
</ul>
|
|
1090
|
+
|
|
626
1091
|
</details>
|
|
1092
|
+
|
|
1093
|
+
##
|
|
1094
|
+
|
|
1095
|
+
- ### Link:
|
|
1096
|
+
|
|
1097
|
+
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
|
|
1098
|
+
|
|
1099
|
+
##
|
|
1100
|
+
|
|
1101
|
+
### 〈♦ API 〉
|
|
1102
|
+
|
|
1103
|
+
- `MorphScroll`: React component that optimizes the rendering of data lists.
|
|
1104
|
+
- `ResizeTracker`: React component that monitors changes to an element’s size.
|
|
1105
|
+
- `IntersectionTracker`: React component for tracking element visibility in the viewport.
|