gatsby-background-image-es5

Speedy, optimized background-images without the work!

gatsby-background-image-es5 is a React component which for background-images provides,
what Gatsby's own gatsby-image does for the rest of your images.

Preamble

This version is completely transpiled to ES5 to target older browsers like IE11! Most polyfills are already built in, though this nearly triples the package size compared to gatsby-background-image!

Everything else just works the same as in gatsby-background-image, so it provides for background-images, what Gatsby's own gatsby-image does for the rest of your images and even more:
Testing explained in its own section. Art-Direction support built in.

It has all the advantages of gatsby-image, including the "blur-up" technique or a "traced placeholder" SVG to show a preview of the image while it loads,
plus having AVIF support (with the help of gbimage-bridge)!
plus being usable as a container (no more hacks with extra wrappers)
plus being able to work with multiple stacked background images
plus being able to style with Tailwind CSS and suchlike Frameworks

All the glamour (and speed) of gatsby-image for your Background Images!

Of course styleable with styled-components and the like!

For usage with Gatsby 3+4's gatsby-plugin-image see:
Gatsby 3+4 & gatsby-plugin-image!

Table of Contents

• Example Repo
• Procedure
• Install
  • Tailwind CSS and suchlike Frameworks
  • Important
• Gatsby 3+4 & gatsby-plugin-image
• How to Use
• How to Use with Multiple Images
• Configuration & props
• Styling & Passed Through Styles
  • Passed Props for styled-components and suchlike
  • Overflow setting
  • Noscript styling
  • Responsive styling
  • Multiple Instances Of Same Component
• Additional props
• Changed props
• props Not Available
• Handling of Remaining props
• Testing gatsby-background-image
• Contributing
• TODO
• Acknowledgements

Example Repo

gatsby-background-image has an example repository to see its similarities & differences to gatsby-image side by side.
It's located at: gbitest To use it with gatsby-background-image-es5 change the dependency there.

Procedure

As gatsby-image is designed to work seamlessly with Gatsby's native image processing capabilities powered by GraphQL and Sharp, so is gatsby-background-image-es5. To produce optimized background-images, you need only to:

1. Import gatsby-background-image-es5 and use it in place of the built-in div or suchlike containers.
2. Write a GraphQL query using one of the GraphQL "fragments" provided by gatsby-transformer-sharp
   which specify the fields needed by gatsby-background-image-es5.

The GraphQL query creates multiple thumbnails with optimized JPEG and PNG compression (or even WebP files for browsers that support them). The gatsby-background-image-es5 component automatically sets up the "blur-up" effect as well as lazy loading of images further down the screen.

Install

To add gatsby-background-image-es5 as a dependency to your Gatsby-project use

npm install --save gatsby-background-image-es5

or

yarn add gatsby-background-image-es5

Depending on the gatsby starter you used, you may need to include gatsby-transformer-sharp and gatsby-plugin-sharp as well, and make sure they are installed and included in your gatsby-config.

npm install --save gatsby-transformer-sharp gatsby-plugin-sharp

or

yarn add gatsby-transformer-sharp gatsby-plugin-sharp

Then in your gatsby-config.js:

plugins: [`gatsby-transformer-sharp`, `gatsby-plugin-sharp`]

Also, make sure you have set up a source plugin, so your images are available in graphql queries. For example, if your images live in a project folder on the local filesystem, you would set up gatsby-source-filesystem in gatsby-config.js like so:

const path = require(`path`)

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: path.join(__dirname, `src`, `images`),
      },
    },
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
  ],
}

Tailwind CSS and suchlike Frameworks

With gatsby-background-image(-es5) @ v0.8.8 it's now possible to use Tailwind CSS classes like md:w-1/2 to style BackgroundImage. Therefore a specialChars plugin option has been introduced to be able to properly escape such classes, which defaults to :/ but may be set to other characters in gatsby-config.js like the following:

module.exports = {
  plugins: [
    ...
    {
      resolve: 'gatsby-background-image-es5',
      options: {
        // add your own characters to escape, replacing the default ':/'
        specialChars: '/:',
      },
    },
    ...
   ],
};

Important:

If you support Safari and/or Internet Explorer, you have to use the IntersectionObserver polyfill.
As - at the time of writing - neither fully implements the feature (see caniuse.com).

This is already the ES5 version of gatsby-background-image, so nothing easier than that! Just add gatsby-background-image-es5 as a plugin to your gatsby-config.js like this:

module.exports = {
  plugins: [
    ...
    `gatsby-background-image-es5`,
    ...
]

Gatsby 3+4 & gatsby-plugin-image

For the moment, until the next major version for gatsby-background-image, the new syntax of image queries is only supported through a companion package called gbimage-bridge. Head over to its README to learn more, but here a TLDR installation instruction:

yarn add gbimage-bridge

or

npm install --save gbimage-bridge

and usage with BackgroundImage is as follows:

import React from 'react'
import { graphql, useStaticQuery } from 'gatsby'
import { getImage, GatsbyImage } from "gatsby-plugin-image"

import { convertToBgImage } from "gbimage-bridge"
import BackgroundImage from 'gatsby-background-image'

const GbiBridged = () => {
  const { placeholderImage } = useStaticQuery(
    graphql`
      query {
        placeholderImage: file(relativePath: { eq: "gatsby-astronaut.png" }) {
          childImageSharp {
            gatsbyImageData(
              width: 200
              placeholder: BLURRED
              formats: [AUTO, WEBP, AVIF]
            )
          }
        }
      }
    `
  )
  const image = getImage(placeholderImage)

  // Use like this:
  const bgImage = convertToBgImage(image)

  return (
    
      <div style="{{minHeight:">
        
      </div>
    
  )
}
export default GbiBridged

But gbimage-bridge has also a BgImage wrapper component for this, so read more over there ; )!

How to Use

Be sure to play around with the Example Repo, as it shows a few more flavors of using BackgroundImage, e.g. encapsulating it in a component : )!

This is what a component using gatsby-background-image-es5 might look like:

import React from 'react'
import { graphql, useStaticQuery } from 'gatsby'
import styled from 'styled-components'

import BackgroundImage from 'gatsby-background-image-es5'

const BackgroundSection = ({ className }) => {
  const data = useStaticQuery(
    graphql`
      query {
        desktop: file(relativePath: { eq: "seamless-bg-desktop.jpg" }) {
          childImageSharp {
            fluid(quality: 90, maxWidth: 1920) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
      }
    `
  )

  // Set ImageData.
  const imageData = data.desktop.childImageSharp.fluid

  return (
    
      <h2>gatsby-background-image</h2>
    
  )
}

const StyledBackgroundSection = styled(BackgroundSection)`
  width: 100%;
  background-position: bottom center;
  background-repeat: repeat-y;
  background-size: cover;
`

export default StyledBackgroundSection

And here is the same component with the data retrieved the old way with the StaticQuery component:

import React from 'react'
import { graphql, StaticQuery } from 'gatsby'
import styled from 'styled-components'

import BackgroundImage from 'gatsby-background-image-es5'

const BackgroundSection = ({ className }) => (
   {
      // Set ImageData.
      const imageData = data.desktop.childImageSharp.fluid
      return (
        
          <h2>gatsby-background-image-es5</h2>
        
      )
    }}
  /&gt;
)

const StyledBackgroundSection = styled(BackgroundSection)`
  width: 100%;
  background-position: bottom center;
  background-repeat: repeat-y;
  background-size: cover;
`

export default StyledBackgroundSection

How to Use with Multiple Images

As gatsby-background-image may be used with multiple backgrounds, including CSS strings like rgba() or suchlike this is what a component using gatsby-background-image-es5 might look like:

import { graphql, useStaticQuery } from 'gatsby'
import React from 'react'
import styled from 'styled-components'

import BackgroundImage from 'gatsby-background-image-es5'

const MultiBackground = ({ children, className }) => {
  const {
    astronaut,
    seamlessBackground,
  } = useStaticQuery(
    graphql`
      query {
        astronaut: file(relativePath: { eq: "astronaut.png" }) {
          childImageSharp {
            fluid(quality: 100) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
        seamlessBackground: file(
          relativePath: { eq: "seamless-background.jpg" }
        ) {
          childImageSharp {
            fluid(quality: 100, maxWidth: 420) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
      }
    `
  )

  // Watch out for CSS's stacking order, especially when styling the
  // individual positions! The lowermost image comes last!
  const backgroundFluidImageStack = [
    seamlessBackground.childImageSharp.fluid,
    `linear-gradient(rgba(220, 15, 15, 0.73), rgba(4, 243, 67, 0.73))`
    astronaut.childImageSharp.fluid,
  ].reverse()

  return (
    
      
        <h2>
          This is a test of multiple background images.
        </h2>
      
    
  )
}

const StyledInnerWrapper = styled.div`
  margin-top: 10%;
  display: flex;
  flex-direction: column;
  align-items: center;
`

const StyledMultiBackground = styled(MultiBackground)`
  width: 100%;
  min-height: 100vh;
  /* You should set a background-size as the default value is "cover"! */
  background-size: auto;
  /* So we won't have the default "lightgray" background-color. */
  background-color: transparent;
  /* Now again, remember the stacking order of CSS: lowermost comes last! */
  background-repeat: no-repeat, no-repeat, repeat;
  background-position: center 155%, center, center;
  color: #fff;
`

export default StyledMultiBackground

How to Use with Art-Direction support

gatsby-background-image-es5 supports showing different images at different breakpoints, which is known as art direction. To do this, you can define your own array of fixed or fluid images, along with a media key per image, and pass it to gatsby-image's fixed or fluid props. The media key that is set on an image can be any valid CSS media query.

Attention: Currently you have to choose between Art-directed and Multiple-Images!

import { graphql, useStaticQuery } from 'gatsby'
import React from 'react'
import styled from 'styled-components'

import BackgroundImage from 'gatsby-background-image-es5'

const ArtDirectedBackground = ({ className }) => {
  const { mobileImage, desktopImage } = useStaticQuery(
    graphql`
      query {
        mobileImage: file(relativePath: { eq: "490x352.jpg" }) {
          childImageSharp {
            fluid(maxWidth: 490, quality: 100) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
        desktopImage: file(relativePath: { eq: "tree.jpg" }) {
          childImageSharp {
            fluid(quality: 100, maxWidth: 4160) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
      }
    `
  )
  // Set up the array of image data and `media` keys.
  // You can have as many entries as you'd like.
  const sources = [
    mobileImage.childImageSharp.fluid,
    {
      ...desktopImage.childImageSharp.fluid,
      media: `(min-width: 491px)`,
    },
  ]

  return (
    
      
        <h2>Hello art-directed gatsby-background-image.</h2>
      
    
  )
}

const StyledInnerWrapper = styled.div`
  margin-top: 10%;
  display: flex;
  flex-direction: column;
  align-items: center;
`

const StyledArtDirectedBackground = styled(ArtDirectedBackground)`
  width: 100%;
  min-height: 100vh;
  /* You should set a background-size as the default value is "cover"! */
  background-size: auto;
  /* So we won't have the default "lightgray" background-color. */
  background-color: transparent;
`

export default StyledArtDirectedBackground

While you could achieve a similar effect with plain CSS media queries, gatsby-background-image-es5 accomplishes this using an internal HTMLPictureElement, as well as window.matchMedia(), which ensures that browsers only download the image they need for a given breakpoint while preventing gatsby-image issue #15189.

Configuration & props

gatsby-background-image nearly works the same as gatsby-image so have a look at their options & props to get started. But be sure to also throw a glance at Additional props, Changed props, props Not Available and Handling of Remaining props as well ; )!

Styling & Passed Through Styles

You may style your gatsby-background-image-es5 BackgroundImage-component every way you like, be it global CSS, CSS-Modules or even with styled-components or your CSS-in-JS "framework" of choice. The style={{}} prop is supported as well.

Whichever way you choose, every background-* style declared in the main class (or the style={{}} prop) will directly get passed through to the pseudo-elements as well (so you would have no need for specifically styling them)!

The specificity hereby is in ascending order:

• class-styles
• extracted background-* styles
• style={{}} prop

The three background- styles seen above are necessary and will default to:

To be able to overwrite them for each pseudo-element individually, you may reset their values in the style={{}} prop with an empty string like such:

style={{
  // Defaults are overwrite-able by setting one or each of the following:
  backgroundSize: '',
  backgroundPosition: '',
  backgroundRepeat: '',
}}

¡But be sure to target the :before and :after pseudo-elements in your CSS, lest your "blurred-up", traced placeholder SVG or lazy loaded background images might jump around!

Passed Props for styled-components and suchlike

Perhaps you want to change the style of a BackgroundImage by passing a prop to styled-components or suchlike CSS-in-JS libraries like e.g. the following:

// isDarken gets changed in the parent component.
const StyledBackground = styled(BackgroundImage)`
  &::before,
  &::after {
    filter: invert(
      ${({ isDarken }) => {
        return isDarken ? '80%' : '0%'
      }}
    );
  }
`

But be aware that there happens no state change inside the BackgroundImage, so React won't rerender it. This can easily be achieved, by settings an additional key prop, which changes as well as the prop like thus:

return 

Overflow setting

As of gatsby-background-image(-es5) @ v0.8.3 the superfluous default of overflow: hidden was removed, as it was only a remnant from the initial creation of gbi (see Acknowledgements for more on its meagre beginnings ; ). As later seen through issue #59, this might break some CSS styling like border-radius, so be sure to include it yourself, should you need such styles. Sorry for the inconvenience % )!

Noscript Styling

As using multiple background images broke with JavaScript disabled, with v0.8.0 we switched to an added `