React Image and Background Image Fade

Fade in images AND background images easily in React ?!

Features

Fade in images and background images ?
️Lazy loading ⚡
Custom loaders ??‍?
Responsive ?
Flexible ??

Install

npm install --save react-image-and-background-image-fade

yarn add react-image-and-background-image-fade

React Image and Background Image Fade
- Demo and Docs are live!
- Features
- Install
- Table of Contents
- Components
  - Image
    - Basic usage
    - Responsive
    - Lazy loading
    - Custom loaders
    - Image Props
  - BackgroundImage
    - Basic Usage
    - Responsive
    - Lazy loading
    - Custom loaders
    - useChild
    - element
    - BackgroundImage Props
  - ImageLoader
    - Overview
    - ImageLoader Props
- Dependencies
- Contributions
- Demo + Examples
- Roadmap
- License

Components

React Image and Background Image Fade comprises of 3 main components:

Image For preloading and fading in img elements
BackgroundImage For preloading and fading in background images of any element.
ImageLoader For creating your own implementation for image loading.

`Image`

Basic usage

Note here that all unknown props like alt and title are passed through to the resulting img element.

import { Image } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <Image
        src='https://example.com/neon_cat.jpg'
        width='300px'
        height='300px'
        alt='flying cat'
        title='Neon cat'
      />
    )
  }
}

Responsive

When using the isResponsive you must ensure that both the width and height are in pixel format, this is because Image calculates the aspect ratio based on the image's width and height. The resulting element will have a width set to 100% and will fill the parent container.

import { Image } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <Image
        src='https://example.com/neon_cat.jpg'
        width='800px'
        height='400px'
        isResponsive
      />
    )
  }
}

Lazy loading

Internally React Image and Background Image Fade makes use of Visibility Sensor. When using lazyLoad the image will begin loading as soon as the image is partially visible in the viewport.

import { Image } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <Image
        src='me_drinking_pina_colada.tiff'
        width='800px'
        height='400px'
        lazyLoad
      />
    )
  }
}

Custom loaders

React Image and Background Image Fade shows a default loader when none is provided which a plain light grey element with an animated 'shine', similar to how Facebook decorate their loading skeletons. You can however specify your own loader element using the renderLoader render prop. This expects a function that renders your custom loader.

hasLoaded is passed to the function so that your loader can be aware that the image is loaded and you can begin your own transition. Note that the loader will be unmounted after the transition time has finished.

hasFailed is so that you an show a custom error in the event of an image load fail.

import { Image } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <Image
        src='me_drinking_pina_colada.tiff'
        width='20%'
        height='10%'
        renderLoader={({ hasLoaded, hasFailed }) => (
          <div className='MyAwesomeLoader'>
            I'm loading here!
            {hasFailed && <span>But I have failed</span>}
            {hasLoaded && (
              <span>
                I'll be here for (transitionTime) milliseconds after load
              </span>
            )}
          </div>
        )}
      />
    )
  }
}

`Image` Props

All initial prop values are undefined unless otherwise specified. src, width and height are the only required props.

Prop	Description
`src` _^string	URI to the image, can be an imported local image or a remote image.
`width` _^string	Width of the image in string format. This can be any valid CSS value such as "20px", "20%", "20em" etc. When using `isResponsive` width must be in px format.
`height` _^string	Height of the image in string format. This can be any valid CSS value such as "20px", "20%", "20em" etc. When using `isResponsive` width must be in px format.
`transitionTime` _{^{string \| default 0.3s}}	Time used for the fade transition. This can be any valid CSS timing value such as "0.3s", "300ms", "3s". This is also used for unmounting the loader component, so once the image has loaded, `<Image/>` will wait for 0.3s (or `transitionTime`) before unmounting the loader.
`renderLoader` _^func	A function that renders a custom loader. The function will call `renderLoader` with an object containing the keys `hasLoaded` and `hasFailed`. See Custom loaders.
`disableLoader` _^bool	Stop loader element from being shown while the image is loading. Note this will override the behaviour of `renderLoader`.
`wrapperClassName` _^string	The `className` to apply to the wrapper element.
`lazyLoad` _{^{bool \| default false}}	Enable or disable lazy loading. See lazy loading.
`isResponsive` _{^{bool \| default false}}	Enable or disable responsiveness. See Responsive.

### `BackgroundImage`

Basic Usage

Note here that all unknown props like alt and title are passed through to the resulting img element.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <BackgroundImage
        src='me_drinking_prosecco.jpg'
        width='300px'
        height='300px'
      />
    )
  }
}

Responsive

When using the isResponsive you must ensure that both the width and height are in pixel format, this is because BackgroundImage calculates the aspect ratio based on the image's width and height. The resulting element will have a width set to 100% and will fill the parent container.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class BackgroundImage extends Component {
  render () {
    return (
      <BackgroundImage
        src='https://example.com/neon_cat.jpg'
        width='800px'
        height='400px'
        isResponsive
      />
    )
  }
}

Lazy loading

Internally React Image and Background Image Fade makes use of Visibility Sensor. When using lazyLoad the image will begin loading as soon as the element is partially visible in the viewport.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <BackgroundImage
        src='me_drinking_pina_colada.tiff'
        width='800px'
        height='400px'
        lazyLoad
      />
    )
  }
}

Custom loaders

hasFailed is so that you an show a custom error in the event of an image load fail.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <BackgroundImage
        src='me_drinking_pina_colada.tiff'
        width='20%'
        height='10%'
        renderLoader={({ hasLoaded, hasFailed }) => (
          <div className='MyAwesomeLoader'>
            I'm loading here!
            {hasFailed && <span>But I have failed</span>}
            {hasLoaded && (
              <span>
                I'll be here for (transitionTime) milliseconds after load
              </span>
            )}
          </div>
        )}
      />
    )
  }
}

useChild

By default BackgroundImage will create its own element to apply the background to however if you would prefer to use your own element you can simply include it within BackgroundImage as a child and set useChild to true.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <BackgroundImage
        useChild
        width='200px'
        height='200px'
        src='me_drinking_guinness.gif'
      >
        <div
          style={{ width: '500px', height: '500px', backgroundSize: 'cover' }}
        >
          I'm in a child wrapper enjoying that sweet background.
        </div>
      </BackgroundImage>
    )
  }
}

element

BackgroundImage creates a wrapper div element and the element that the background is attached to is by default a div this can be changed to any other valid html element. If you would like to apply the background image to a custom component, see useChild.

import { BackgroundImage } from 'react-image-and-background-image-fade'

class Example extends Component {
  render () {
    return (
      <BackgroundImage
        element='p'
        width='200px'
        height='200px'
        src='me_drinking_guinness.gif'
      >
        Look at me i'm a paragraph.
      </BackgroundImage>
    )
  }
}

`BackgroundImage` Props

All initial prop values are undefined unless otherwise specified. src, width and height are the only required props.

Prop	Description
`src` _^string	URI to the image, can be an imported local image or a remote image.
`width` _^string	Width of the element in string format. This can be any valid CSS value such as "20px", "20%", "20em" etc. When using `isResponsive` width must be in px format.
`height` _^string	Height of the element in string format. This can be any valid CSS value such as "20px", "20%", "20em" etc. When using `isResponsive` width must be in px format.
`transitionTime` _{^{string \| default 0.3s}}	Time used for the fade transition. This can be any valid CSS timing value such as "0.3s", "300ms", "3s". This is also used for unmounting the loader component, so once the image has loaded, `BackgroundImage` will wait for 0.3s (or `transitionTime`) before unmounting the loader.
`renderLoader` _^func	A function that renders a custom loader. The function will call `renderLoader` with an object containing the keys `hasLoaded` and `hasFailed`. See Custom loaders.
`disableLoader` _^bool	Stop loader element from being shown while the image is loading. Note this will override the behaviour of `renderLoader`.
`wrapperClassName` _^string	The `className` to apply to the wrapper element.
`lazyLoad` _{^{bool \| default false}}	Enable or disable lazy loading. See lazy loading.
`isResponsive` _{^{bool \| default false}}	Enable or disable responsiveness. See Responsive.
`useChild` _{^{bool \| default false}}	Whether or not to use the child as the element to apply the background image to. See useChild.
`element` _^string	The string element name of the element you would like `BackgroundImage` to create and apply the background image too. See element.

`ImageLoader`

Overview

Both Image and BackgroundImage make use of ImageLoader internally. It can be useful for creating your own loader and any advanced use case that the other two components can't cater for.

ImageLoader is used via a render prop as the child. The method provided as the child will be called with an object with the following keys:

hasLoaded (bool) - True when image retrieval was success
shouldShowLoader (bool) - True when the loader should be shown, this is useful for when the image has loaded but you want to continue to keep the loader mounted for transitionTime seconds to complete the transition.
hasFailed (bool) - True when retrieving the image was unsuccessful
src (string) - The source of the image (pass-through)

import { ImageLoader } from 'react-image-and-background-image-fade'

class AwesomeOLoader extends Component {
  render () {
    return (
      <ImageLoader src='awesome-o.gif' transitionTime='0.3s'>
        {({ hasLoaded, shouldShowLoader, hasFailed, src }) => (
          <div className='AwesomeOLoader'>
            {shouldShowLoader && !hasFailed && (
              <div className='AwesomeoLoader__loading'>
                Awesome-o is loading ...
              </div>
            )}

            {hasFailed && (
              <div className='AwesomeoLoader__failed'>
                Awesome-o has failed :(
              </div>
            )}

            {hasLoaded && (
              <div
                className='AwesomeoLoader__failed'
                style={{ backgroundImage: `url(${src})` }}
              >
                Awesome-o has Loaded!! :(
              </div>
            )}
          </div>
        )}
      </ImageLoader>
    )
  }
}

`ImageLoader` Props

All initial prop values are undefined unless otherwise specified. src and children.

Prop	Description
`src` _^string	URI to the image, can be an imported local image or a remote image.
`transitionTime` _{^{string \| default 0.3s}}	Time used for the transition. This can be any valid CSS timing value such as "0.3s", "300ms", "3s". Works in conjunction with `shouldShowLoader`. See ImageLoader.
`lazyLoad` _{^{bool \| default false}}	Enable or disable lazy loading. See lazy loading.
`children`	Render prop to render. Calls `children` with the following: `({ hasLoaded, shouldShowLoader, hasFailed, src })`. See Overview.

Dependencies

React Image and Background Image is not a depency-free component. It aims to provide a fully featured and flexible solution for image and background preloading. It makes use of the following awesome npm packages:

ImagePreloader - Under the hood for the actual preloading of the image
React Visibility Sensor - Lazy load functionality
Styled Components - Dynamic styling under the hood

Contributions

React Image and Background Image is very young at the moment and thoroughly encourages pull requests and issues.

React Image and Background Image Fade

Features

Install

Table of Contents

Components

Image

Basic usage

Responsive

Lazy loading

Custom loaders

Image Props

Basic Usage

Responsive

Lazy loading

Custom loaders

useChild

element

BackgroundImage Props

ImageLoader

Overview

ImageLoader Props

Dependencies

Contributions

Demo + Examples

Roadmap

License

`Image`

`Image` Props

`BackgroundImage` Props

`ImageLoader`

`ImageLoader` Props