You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Two components: a HOC to track the scroll position and a component to render the image.
10
-
* Handles scroll events, resize events and re-renders that might change the position of the components.
11
-
* Placeholder by default with the same size of the image.
12
-
* A custom placeholder and threshold can be specified.
13
+
* Includes two components (`LazyLoadImage` and `LazyLoadComponent`) and a HOC (`trackWindowScroll`) which adds scroll position tracking to any component you wish.
14
+
* Handles scroll events, resize events and re-renders that might change the position of the components. And, of course, above-the-fold on initial render.
15
+
* Placeholder by default with the same size of the image/component.
16
+
* A custom placeholder component or image can be specified.
17
+
* Built-in on-visible effects (blur, black and white and opacity transitions).
18
+
* threshold is set to 100px by default and can be modified.
13
19
*`beforeLoad` and `afterLoad` events.
14
-
* Accepts all standard `<img>` attributes.
15
-
* No dependencies other than `react` and `react-dom`.
16
-
20
+
*`debounce` and `throttle` included by default and configurable.
17
21
18
22
## Installation
19
23
20
-
1. Install react-lazy-load-image-component as a dependency:
src={image.src} // use normal <img> attributes as props
45
+
width={image.width} />
46
+
<span>{image.caption}</span>
47
+
</div>
48
+
);
49
+
50
+
exportdefaultMyImage;
31
51
```
32
52
33
-
3. Import the trackWindowScroll HOC:
53
+
### Props
54
+
55
+
| Prop | Type | Default | Description |
56
+
|:---|:---|:---|:---|
57
+
| afterLoad |`Function`|| Function called after the image has been completely loaded. |
58
+
| beforeLoad |`Function`|| Function called right before the placeholder is replaced with the image element. |
59
+
| delayMethod |`String`|`throttle`| Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
60
+
| delayTime |`String`| 300 | Time in ms sent to the delayMethod. |
61
+
| effect |`String`|| Name of the effect to use. Please, read next section with an explanation on how to use them. |
62
+
| placeholder |`ReactClass`|`<span>`| React element to use as a placeholder. |
63
+
| placeholderSrc |`String`|| Image src to display while the image is not visible or loaded. |
64
+
| threshold |`Number`| 100 | Threshold in pixels. So the image starts loading before it appears in the viewport. |
65
+
| visibleByDefault |`Boolean`| false | Whether the image must be visible from the beginning. |
66
+
| ... ||| Any other image attribute |
67
+
68
+
69
+
### Using effects
70
+
71
+
`LazyLoadImage` includes several effects ready to be used, they are useful to add visual candy to your application, but are completely optional in case you don't need them or want to implement some other effect.
72
+
73
+
They rely on CSS and the corresponding CSS file must be imported:
* blur: renders a blurred image based on `placeholderSrc` and transitions to a non-blurred one when the image specified in the src is loaded.
91
+
* black-and-white: renders a black and white image based on `placeholderSrc` and transitions to a colorful image when the image specified in the src is loaded.
92
+
* opacity: renders a blank space and transitions to full opacity when the image is loaded.
| afterLoad |`Function`|| Function called after the component has been rendered. |
119
+
| beforeLoad |`Function`|| Function called right before the component is rendered. |
120
+
| delayMethod |`String`|`throttle`| Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
121
+
| delayTime |`String`| 300 | Time in ms sent to the delayMethod from lodash. |
122
+
| placeholder |`ReactClass`|`<span>`| React element to use as a placeholder. |
123
+
| threshold |`Number`| 100 | Threshold in pixels. So the component starts loading before it appears in the viewport. |
124
+
| visibleByDefault |`Boolean`| false | Whether the component must be visible from the beginning. |
125
+
126
+
127
+
## Using `trackWindowScroll` HOC to improve performance
128
+
129
+
When you have many elements to lazy load in the same page, you might get poor performance because each one is listening to the scroll/resize events. In that case, it's better to wrap the deepest common parent of those components with a HOC to track those events (`trackWindowScroll`).
130
+
131
+
For example, if we have an `App` which renders a `Gallery`, we would wrap the `Gallery` component with the HOC.
You must set the prop `scrollPosition` to the lazy load components. This way, they will know the scroll/resize events are tracked by a parent component and will not subscribe to them.
160
+
161
+
### Props
162
+
163
+
`LazyLoadImage`
164
+
165
+
| Prop | Type | Default | Description |
166
+
|:---|:---|:---|:---|
167
+
| scrollPosition |`Object`|| Object containing `x` and `y` with the curent window scroll position. Required. |
168
+
| afterLoad |`Function`|| Function called after the image has been rendered. |
169
+
| beforeLoad |`Function`|| Function called right before the image is rendered. |
170
+
| placeholder |`ReactClass`|`<span>`| React element to use as a placeholder. |
171
+
| threshold |`Number`| 100 | Threshold in pixels. So the image starts loading before it appears in the viewport. _Defaults to 100._|
172
+
| visibleByDefault |`Boolean`| false | Whether the image must be visible from the beginning. |
173
+
| ... ||| Any other image attribute |
174
+
175
+
Component wrapped with `trackWindowScroll` (in the example, `Gallery`)
176
+
177
+
| Prop | Type | Default | Description |
178
+
|:---|:---|:---|:---|
179
+
| delayMethod |`String`|`throttle`| Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
180
+
| delayTime |`String`| 300 | Time in ms sent to the delayMethod from lodash. |
181
+
182
+
Notice you can do the same replacing `LazyLoadImage` with `LazyLoadComponent`.
183
+
184
+
185
+
## When to use `visibleByDefault`?
65
186
66
-
| Prop | Type | Description |
67
-
|:---|:---|:---|
68
-
| scrollPosition |`Object`| Object containing `x` and `y` with the curent window scroll position. Required. |
69
-
| afterLoad |`Function`| Function called after the image has been rendered. |
70
-
| beforeLoad |`Function`| Function called right before the image is rendered. |
71
-
| placeholder |`ReactClass`| A React element to use as a placeholder. |
72
-
| threshold |`Number`| Threshold in pixels. So the image starts loading before it appears in the viewport. _Defaults to 100._|
73
-
| visibleByDefault |`Boolean`| Whether the image must be visible from the beginning. |
74
-
| ... || Any other image attribute |
187
+
The prop `visibleByDefault` makes the LazyLoadImage to behave like a normal `<img>`. Why is it useful, then?
188
+
189
+
Imagine you are going to lazy-load an image you have already loaded in the same page. In that case, there is no need to lazy-load it because it's already stored in the cache of the user's browser. You can directly display it.
190
+
191
+
Maybe the following code snippet will make it more clear:
Get the [full code of this example](https://github.com/Aljullu/weather-app).
224
+
225
+
226
+
## Common errors
227
+
228
+
### Warning: setState(...): Can only update a mounted or mounting component.
229
+
230
+
That warning might appear if there are two components using `trackWindowScroll` at the same time. Notice it's not possible to have a LazyLoadImage/LazyLoadComponent inside another LazyLoadComponent for now. Also, make sure you are passing down `scrollPosition` to all components wrapped inside `trackWindowScroll`.
0 commit comments