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

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 { 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>
    );
  }
}

Props

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