react-image-measurer v1.0.1
react-image-measurer
Preload and measure images in React virtualized lists easily
Overview
When dealing with virtualized lists, dynamically-sized elements like images might be a bit of a chicken and egg situation: you cannot really know the size of an image before downloading and rendering it in the DOM, but to size your virtualized list properly, you need to know about the height of your blocks (incl. images) before ever rendering them for your users.
A quick solution to this problem is to preload and measure the images out of view so that your virtualized list can know about your images' dimensions before they are rendered into view. Given that your user hasn't disabled their browser's cache, this also means that when they'll reach the image for the first time, they won't have to do any network fetching before being able to see images.
This project was born as an attempt to fix perceived shortcomings of and improve on react-virtualized-image-measurer.
Install
You can add the preloader component to your project using yarn add react-image-preloader.
Usage
The preloader is a wrapper component the container in which your images will appear. It's usage is simple:
import ImagePreloader from 'react-image-measurer'
...
<ImagePreloader
...preloaderProps
>
{({ dimensions }) => <MyContainer imageDimensions={dimensions} />}
</ImagePreloader>You can pass a number of props to the ImagePreloader component to tailor its behaviour to your use case:
| Prop | Required | Default | Definition | |
|---|---|---|---|---|
blockWhileLoading | Optional | false | (bool) Whether the preloader will render the loadingFallback until it has all the image sizes or not | |
children | Required | - | - | |
clearOnceLoaded | Optional | false | (bool) If true, the components used to preload the images will be purged from the DOM once the preloading is done. | |
defaultDimensions | Required | - | (object) A { height, width } object defining default dimensions if preloading fails for an image | |
imageSelector | Required | - | (func) Function used to get the image url off a single item in items | |
keySelector | Optional | () => null | (func) Function used to determine under what key the size of a certain image should be stored. Defaults to indices from items | |
loadingFallback | Optional | null | (node | func) The fallback component rendered while loading if blockWhileLoading is true |
items | Required | - | (array | iterable by value) The list of items to process |
itemCount|__Required__|-|(integer) The number of items in theitems` collection | ||||
onError | Optional | () => null | func) Function executed on an image if it fails to load | |
onLoad | Optional | () => null | (func) Function executed on an image when it is done loading | |
onLoaded | Optional | () => null | (func) Function executed once all of the images are done loading or have errored out |
Callbacks
onError / onLoad
onLoad is called on an image when it is done loading, onError is called instead if the image fails to load (for example, if the return code for the request is 4xx).
Because this depends on the speed at which each image loads (or fails to), the calls to these callbacks may not be in the same order as the items list.
({ src, status, key, height, width }) => { ... } Parameters
|Parameter|Definition|
|---|---|
|src|The URL of the image|
|status|Status as defined in constants.js. Set to error (imageStates.ERROR) following a failure or loaded (imageStates.LOADED) on success|
|key|Either the index of the image as per the original items collection, or the key defined by keyMapper|
|height|The default height provided to the preloader, or the measured height if preloading succeeded|
|width|The default width provided to the preloader, or the measured width if the preloading succeeded|
onLoaded
onLoaded is called just before the final render, when every image in the items list is either loaded or has failed to load. It takes no arguments.
Contributing
TODO