Skip to content

Commit 37c3b34

Browse files
CCherry07CCherry07
committed
feat: add readme
1 parent 639b620 commit 37c3b34

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎README.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
2+
## Installation
3+
4+
```bash
5+
# Yarn
6+
$ yarn add vue-lazy-load-image-component
7+
8+
# NPM
9+
$ npm i --save vue-lazy-load-image-component
10+
```
11+
12+
## `LazyLoadImage` usage
13+
14+
```javascript
15+
import React from 'react';
16+
import { LazyLoadImage } from 'vue-lazy-load-image-component';
17+
18+
const MyImage = ({ image }) => (
19+
<div>
20+
<LazyLoadImage
21+
alt={image.alt}
22+
height={image.height}
23+
src={image.src} // use normal <img> attributes as props
24+
width={image.width} />
25+
<span>{image.caption}</span>
26+
</div>
27+
);
28+
29+
export default MyImage;
30+
```
31+
32+
### Props
33+
34+
| Prop | Type | Default | Description |
35+
|:---|:---|:---|:---|
36+
| afterLoad | `Function` | | Function called after the image has been completely loaded. |
37+
| beforeLoad | `Function` | | Function called right before the placeholder is replaced with the image element. |
38+
| delayMethod | `String` | `throttle` | Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
39+
| delayTime | `Number` | 300 | Time in ms sent to the delayMethod. |
40+
| effect | `String` | | Name of the effect to use. Please, read next section with an explanation on how to use them. |
41+
| placeholder | `ReactClass` | `<span>` | React element to use as a placeholder. |
42+
| placeholderSrc | `String` | | Image src to display while the image is not visible or loaded. |
43+
| threshold | `Number` | 100 | Threshold in pixels. So the image starts loading before it appears in the viewport. |
44+
| useIntersectionObserver | `Boolean` | true | Whether to use browser's IntersectionObserver when available. |
45+
| visibleByDefault | `Boolean` | false | Whether the image must be visible from the beginning. |
46+
| wrapperClassName | `String` | | In some occasions (for example, when using a placeholderSrc) a wrapper span tag is rendered. This prop allows setting a class to that element. |
47+
| wrapperProps | `Object` | null | Props that should be passed to the wrapper span when it is rendered (for example, when using placeholderSrc or effect) |
48+
| ... | | | Any other image attribute |
49+
50+
### Using effects
51+
52+
`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 you own effect.
53+
54+
They rely on CSS and the corresponding CSS file must be imported:
55+
56+
```javascript
57+
import React from 'react';
58+
import { LazyLoadImage } from 'vue-lazy-load-image-component';
59+
import 'vue-lazy-load-image-component/lib/style.css';
60+
61+
const MyImage = ({ image }) => (
62+
<LazyLoadImage
63+
alt={image.alt}
64+
effect="blur"
65+
src={image.src} />
66+
);
67+
```
68+
69+
The current available effects are:
70+
71+
* `blur`: renders a blurred image based on `placeholderSrc` and transitions to a non-blurred one when the image specified in the src is loaded.
72+
73+
![Screenshot of the blur effect](https://user-images.githubusercontent.com/3616980/37790728-9f95529a-2e07-11e8-8ac3-5066c065e0af.gif)
74+
75+
* `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.
76+
77+
![Screenshot of the black-and-white effect](https://user-images.githubusercontent.com/3616980/37790682-864e58d6-2e07-11e8-8984-ad5d7b056d9f.gif)
78+
79+
* `opacity`: renders a blank space and transitions to full opacity when the image is loaded.
80+
81+
![Screenshot of the opacity effect](https://user-images.githubusercontent.com/3616980/37790755-b48a704a-2e07-11e8-91c3-fcd43a91e7b1.gif)
82+
83+
## `LazyLoadComponent` usage
84+
85+
```javascript
86+
import React from 'react';
87+
import { LazyLoadComponent } from 'vue-lazy-load-image-component';
88+
import { ArticleContent, ArticleComments } from 'my-app';
89+
90+
const Article = ({ articleId }) => (
91+
<div>
92+
<ArticleContent id={articleId} />
93+
<LazyLoadComponent>
94+
<ArticleComments id={articleId} />
95+
</LazyLoadComponent>
96+
</div>
97+
);
98+
99+
export default Article;
100+
```
101+
102+
### Props
103+
104+
| Prop | Type | Default | Description |
105+
|:---|:---|:---|:---|
106+
| afterLoad | `Function` | | Function called after the component has been rendered. |
107+
| beforeLoad | `Function` | | Function called right before the component is rendered. |
108+
| delayMethod | `String` | `throttle` | Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
109+
| delayTime | `Number` | 300 | Time in ms sent to the delayMethod from lodash. |
110+
| placeholder | `ReactClass` | `<span>` | React element to use as a placeholder. |
111+
| threshold | `Number` | 100 | Threshold in pixels. So the component starts loading before it appears in the viewport. |
112+
| useIntersectionObserver | `Boolean` | true | Whether to use browser's IntersectionObserver when available. |
113+
| visibleByDefault | `Boolean` | false | Whether the component must be visible from the beginning. |
114+
115+
## Using `trackWindowScroll` HOC to improve performance
116+
117+
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`).
118+
119+
For example, if we have an `App` which renders a `Gallery`, we would wrap the `Gallery` component with the HOC.
120+
121+
```javascript
122+
import React from 'react';
123+
import { LazyLoadImage, trackWindowScroll }
124+
from 'vue-lazy-load-image-component';
125+
126+
const Gallery = ({ images, scrollPosition }) => (
127+
<div>
128+
{images.map((image) =>
129+
<LazyLoadImage
130+
key={image.key}
131+
alt={image.alt}
132+
height={image.height}
133+
// Make sure to pass down the scrollPosition,
134+
// this will be used by the component to know
135+
// whether it must track the scroll position or not
136+
scrollPosition={scrollPosition}
137+
src={image.src}
138+
width={image.width} />
139+
)}
140+
</div>
141+
);
142+
// Wrap Gallery with trackWindowScroll HOC so it receives
143+
// a scrollPosition prop to pass down to the images
144+
export default trackWindowScroll(Gallery);
145+
```
146+
147+
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.
148+
149+
### Props
150+
151+
`LazyLoadImage`
152+
153+
| Prop | Type | Default | Description |
154+
|:---|:---|:---|:---|
155+
| scrollPosition | `Object` | | Object containing `x` and `y` with the curent window scroll position. Required. |
156+
| afterLoad | `Function` | | Function called after the image has been rendered. |
157+
| beforeLoad | `Function` | | Function called right before the image is rendered. |
158+
| placeholder | `ReactClass` | `<span>` | React element to use as a placeholder. |
159+
| threshold | `Number` | 100 | Threshold in pixels. So the image starts loading before it appears in the viewport. |
160+
| visibleByDefault | `Boolean` | false | Whether the image must be visible from the beginning. |
161+
| wrapperProps | `Object` | null | Props that should be passed to the wrapper span when it is rendered (for example, when using placeholderSrc or effect) |
162+
| ... | | | Any other image attribute |
163+
164+
Component wrapped with `trackWindowScroll` (in the example, `Gallery`)
165+
166+
| Prop | Type | Default | Description |
167+
|:---|:---|:---|:---|
168+
| delayMethod | `String` | `throttle` | Method from lodash to use to delay the scroll/resize events. It can be `throttle` or `debounce`. |
169+
| delayTime | `Number` | 300 | Time in ms sent to the delayMethod from lodash. |
170+
| useIntersectionObserver | `Boolean` | true | Whether to use browser's IntersectionObserver when available. |
171+
172+
Notice you can do the same replacing `LazyLoadImage` with `LazyLoadComponent`.
173+
174+
## When to use `visibleByDefault`?
175+
176+
The prop `visibleByDefault` makes the LazyLoadImage to behave like a normal `<img>`. Why is it useful, then?
177+
178+
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.
179+
180+
Maybe the following code snippet will make it more clear:
181+
182+
```javascript
183+
import React from 'react';
184+
import { LazyLoadImage, trackWindowScroll }
185+
from 'vue-lazy-load-image-component';
186+
187+
const Gallery = ({ images, scrollPosition }) => (
188+
<div>
189+
// We are loading landscape.jpg here
190+
<img src="/landscape.jpg" alt="Beautiful landscape" />
191+
{images.map((image) =>
192+
<LazyLoadImage
193+
key={image.key}
194+
alt={image.alt}
195+
scrollPosition={scrollPosition}
196+
src={image.src}
197+
// If the image we are creating here has the same src than before,
198+
// we can directly display it with no need to lazy-load.
199+
visibleByDefault={image.src === '/landscape.jpg'} />
200+
)}
201+
</div>
202+
);
203+
204+
export default trackWindowScroll(Gallery);
205+
```

0 commit comments

Comments
 (0)