react-lazyload

What is react-lazyload?

The react-lazyload package is a React component that provides lazy loading functionality for images and other components. It helps improve performance by deferring the loading of offscreen elements until they are about to enter the viewport.

What are react-lazyload's main functionalities?

Basic Lazy Loading

This feature allows you to lazy load an image. The image will only load when it is about to enter the viewport, improving performance by not loading offscreen images.

import React from 'react';
import LazyLoad from 'react-lazyload';

const App = () => (
  <div>
    <LazyLoad height={200} offset={100}>
      <img src="path/to/image.jpg" alt="Lazy Loaded Image" />
    </LazyLoad>
  </div>
);

export default App;

Placeholder

This feature allows you to display a placeholder image while the actual image is being lazy loaded. This can improve user experience by showing a temporary image until the main image is loaded.

import React from 'react';
import LazyLoad from 'react-lazyload';

const App = () => (
  <div>
    <LazyLoad height={200} placeholder={<img src="path/to/placeholder.jpg" alt="Placeholder" />}>
      <img src="path/to/image.jpg" alt="Lazy Loaded Image" />
    </LazyLoad>
  </div>
);

export default App;

Debounce and Throttle

This feature allows you to control the rate at which the lazy loading function is called. Debounce delays the function call until after a specified delay, while throttle ensures the function is called at most once in a specified time period.

import React from 'react';
import LazyLoad from 'react-lazyload';

const App = () => (
  <div>
    <LazyLoad height={200} debounce={300}>
      <img src="path/to/image.jpg" alt="Lazy Loaded Image" />
    </LazyLoad>
    <LazyLoad height={200} throttle={200}>
      <img src="path/to/image2.jpg" alt="Lazy Loaded Image" />
    </LazyLoad>
  </div>
);

export default App;

Other packages similar to react-lazyload

react-intersection-observer

react-intersection-observer is a React implementation of the Intersection Observer API. It provides a way to observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport. It is more flexible and can be used for a variety of use cases beyond lazy loading.

react-lazy-load

react-lazy-load is another React component for lazy loading content. It is simple to use and provides basic lazy loading functionality. It is less feature-rich compared to react-lazyload but can be a good choice for simpler use cases.

README

Note

This project is now currently maintained by @ameerthehacker, please reach out to him on any issues or help.

react-lazyload

Lazyload your Components, Images or anything matters the performance.

Demo

Why it's better

• Take performance in mind, only 2 event listeners for all lazy-loaded components
• Support both one-time lazy load and continuous lazy load mode
• scroll / resize event handler is throttled so you won't suffer frequent update, you can switch to debounce mode too
• Decorator supported
• Server Side Rendering friendly
• Thoroughly tested

Installation

2.0.0 is finally out, read Upgrade Guide, it's almost painless to upgrade!

$ npm install --save react-lazyload

Usage

import React from 'react';
import ReactDOM from 'react-dom';
import LazyLoad from 'react-lazyload';
import MyComponent from './MyComponent';

const App = () => {
  return (
    <div className="list">
      <LazyLoad height={200}>
        <img src="tiger.jpg" /> /*
                                  Lazy loading images is supported out of box,
                                  no extra config needed, set `height` for better
                                  experience
                                 */
      </LazyLoad>
      <LazyLoad height={200} once >
                                /* Once this component is loaded, LazyLoad will
                                 not care about it anymore, set this to `true`
                                 if you're concerned about improving performance */
        <MyComponent />
      </LazyLoad>
      <LazyLoad height={200} offset={100}>
                              /* This component will be loaded when it's top
                                 edge is 100px from viewport. It's useful to
                                 make user ignorant about lazy load effect. */
        <MyComponent />
      </LazyLoad>
      <LazyLoad>
        <MyComponent />
      </LazyLoad>
    </div>
  );
};

ReactDOM.render(<App />, document.body);

If you want to have your component lazyloaded by default, try this handy decorator:

import { lazyload } from 'react-lazyload';

@lazyload({
  height: 200,
  once: true,
  offset: 100
})
class MyComponent extends React.Component {
  render() {
    return <div>this component is lazyloaded by default!</div>;
  }
}

Special Tips

You should be aware that your component will only be mounted when it's visible in viewport, before that a placeholder will be rendered.

So you can safely send request in your component's componentDidMount without worrying about performance loss or add some pretty entering effects, see this demo for more detail.

Props

children

Type: Node Default: undefined

NOTICE Only one child is allowed to be passed.

scrollContainer

Type: String/DOM node Default: undefined

Pass a query selector string or DOM node. LazyLoad will attach to the window object's scroll events if no container is passed.

height

Type: Number/String Default: undefined

In the first round of render, LazyLoad will render a placeholder for your component if no placeholder is provided and measure if this component is visible. Set height properly will make LazyLoad calculate more precisely. The value can be number or string like '100%'. You can also use css to set the height of the placeholder instead of using height.

once

Type: Bool Default: false

Once the lazy loaded component is loaded, do not detect scroll/resize event anymore. Useful for images or simple components.

offset

Type: Number/Array(Number) Default: 0

Say if you want to preload a component even if it's 100px below the viewport (user have to scroll 100px more to see this component), you can set offset props to 100. On the other hand, if you want to delay loading a component even if it's top edge has already appeared at viewport, set offset to negative number.

Library supports horizontal lazy load out of the box. So when you provide this prop with number like 100 it will automatically set left edge offset to 100 and top edge to 100;

If you provide this prop with array like [100, 200], it will set left edge offset to 100 and top offset to 200.

scroll

Type: Bool Default: true

Listen and react to scroll event.

resize

Type: Bool Default: false

Respond to resize event, set it to true if you do need LazyLoad listen resize event.

NOTICE If you tend to support legacy IE, set this props carefully, refer to this question for further reading.

overflow

Type: Bool Default: false

If lazy loading components inside a overflow container, set this to true. Also make sure a position property other than static has been set to your overflow container.

demo

placeholder

Type: Any Default: undefined

Specify a placeholder for your lazy loaded component.

demo

If you provide your own placeholder, do remember add appropriate height or minHeight to your placeholder element for better lazyload performance.

unmountIfInvisible

Type: Bool Default: false

The lazy loaded component is unmounted and replaced by the placeholder when it is no longer visible in the viewport.

debounce/throttle

Type: Bool / Number Default: undefined

Lazyload will try to use passive event by default to improve scroll/resize event handler's performance. If you prefer control this behaviour by yourself, you can set debounce or throttle to enable built in delay feature.

If you provide a number, that will be how many ms to wait; if you provide true, the wait time defaults to 300ms.

NOTICE Set debounce / throttle to all lazy loaded components unanimously, if you don't, the first occurrence is respected.

demo

wheel

DEPRECATED NOTICE This props is not supported anymore, try set overflow for lazy loading in overflow containers.

Utility

forceCheck

It is available to manually trigger checking for elements in viewport. Helpful when LazyLoad components enter the viewport without resize or scroll events, e.g. when the components' container was hidden then become visible.

Import forceCheck:

import { forceCheck } from 'react-lazyload';

Then call the function:

forceCheck();

Scripts

$ npm run demo:watch
$ npm run build

Who should use it

Let's say there is a fixed date picker on the page, when user picks a different date, all components displaying data should send ajax requests with new date parameter to retreive updated data, even many of them aren't visible in viewport. This makes server load furious when there are too many requests in one time.

Using LazyLoad component will help ease this situation by only updating components visible in viewport.

Contributors

• lancehub
• doug-wade

License

MIT