3.3.0 • Published 4 months ago

loadable-image v3.3.0

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

loadable-image

NPM Version storybook NPM Downloads GitHub Repo stars

React Component to lazy load images.

Edit loadable-image

Installation

npm i loadable-image

Or via yarn

yarn add loadable-image

Usage examples

<AsyncImage /> accepts all props of <img /> tag.

import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='https://picsum.photos/1900'
  style={{ width: 150, height: 150 }}
/>

Custom Loader/Error

You can pass your own loader and error components as props to AsyncImage component.

import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='https://picsum.photos/1900'
  style={{ width: 150, height: 150 }}
  loader={<div style={{ background: '#888' }}/>}
  error={<div style={{ background: '#eee' }}/>}
/>

Modern formats (WebP, Avif) with fallback

Since under the hood <AsyncImage /> is just a picture element. You can pass an array of different Sources as a prop. And browser will pick the first one that it supports.

import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src="./image.jpg"
  sources={[ 
      { type:"image/avif",  srcSet:"./image.avif" }, 
      { type:"image/webp",  srcSet:"./image.webp" } 
  ]}
  style={{ width: 200, height: 200 }}
/>

Responsive image

To make image responsive you can use aspectRatio property in style prop. This way you can specify only width or height as 100% and the other one as auto. Note that if you support older browsers you might need to use aspectRatio padding-hack.

import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='https://picsum.photos/1900'
  style={{ width: "100%", height: "auto", aspectRatio: 16 / 9 }}
/>

Custom Transitions

Under the hood AsyncImage uses transitions-kit library it's a collection Transition components built on top of react-transition-group its a small library maintained by React team for animating between different views. You can pass your own Transition as a prop to AsyncImage component.

Blur transition

Here’s how you can implement a Blur transition that replaces a low-resolution image with a high-resolution one

import { Blur } from 'transitions-kit'
import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='./original-image.jpg'
  style={{ width: 150, height: 150 }}
  Transition={props => <Blur radius={10} {...props}/>}
  loader={<img src='./extra-small-1x1.jpg' />}
/>

Fade transition

By default AsyncImage uses Fade transition.

import { Fade } from 'transitions-kit'
import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='https://picsum.photos/1900'
  style={{ width: 150, height: 150 }}
  loader={<div style={{ background: '#888' }}/>}
  Transition={Fade}
/>

Other transitions

There are plenty different already predefined Transition components such as Grow, Zoom, Slide, Blur, Fade etc. in transitions-kit. Feel free to try any of them.

import { Grow } from 'transitions-kit'
import { AsyncImage } from 'loadable-image'
...
<AsyncImage
  src='https://picsum.photos/1900'
  style={{ width: 150, height: 150 }}
  loader={<div style={{ background: '#888' }}/>}
  Transition={Grow}
/>

Props

<AsyncImage /> accepts all standard props for HtmlImageElement and the following:

PropertyTypeDescription
classNameStringNOTE: CSS from style object has a higher priority
styleCSSPropertiesCSSStyleDeclaration object
rootMarginstring by default: '600px 0px'Margin around the root. Specifies when to trigger an image download.
loaderReactElementReact element to display a loading state.
errorReactElementReact element to display an error state.
sourcesArray<SourceProps>An array of options for <source /> element.
timeoutNumber or ObjectThe duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object.
TransitionComponentType<TransitionProps>Custom Transition component. Check out transitions-kit's predefined components

Requirements for loader & error props:

  • Forward the ref: The transition components require the first child element to forward its ref to the DOM node. This is usually done with React.forwardRef.
  • Single element: The transition components require only one child element (React.Fragment is not allowed).
3.3.0

4 months ago

3.2.6

11 months ago

3.2.5

11 months ago

3.2.2

1 year ago

3.2.3

1 year ago

3.2.1

1 year ago

3.2.0

1 year ago

3.1.1

1 year ago

3.1.0

1 year ago

3.0.4

2 years ago

3.0.3

2 years ago

3.0.2

2 years ago

3.0.1

2 years ago

3.0.6

2 years ago

3.0.5

2 years ago

3.0.0

2 years ago

2.3.0

2 years ago

2.3.1

2 years ago

1.2.7

2 years ago

2.2.1

2 years ago

2.1.2

2 years ago

2.0.3

2 years ago

2.1.1

2 years ago

2.0.2

2 years ago

2.1.4

2 years ago

2.0.5

2 years ago

2.2.2

2 years ago

2.1.3

2 years ago

2.0.4

2 years ago

2.0.7

2 years ago

2.1.5

2 years ago

2.0.6

2 years ago

2.0.9

2 years ago

2.0.8

2 years ago

2.1.0

2 years ago

2.0.1

2 years ago

2.0.0

2 years ago

1.2.6

2 years ago

1.2.5

2 years ago

1.1.1

3 years ago

1.1.0

3 years ago

1.1.9

3 years ago

1.1.8

3 years ago

1.1.5

3 years ago

1.2.3

3 years ago

1.2.2

3 years ago

1.1.3

3 years ago

1.2.1

3 years ago

1.1.2

3 years ago

1.1.10

3 years ago

1.0.14

3 years ago

1.0.13

3 years ago

1.0.12

3 years ago

1.0.11

3 years ago

1.0.10

3 years ago

1.0.9

3 years ago

1.0.8

3 years ago

1.0.7

3 years ago

1.0.6

3 years ago

1.0.5

3 years ago

1.0.4

3 years ago

1.0.3

3 years ago

1.0.1

3 years ago

1.0.0

3 years ago