gatsby-background-image

Speedy, optimized background-images without the work!

gatsby-background-image is a React component based on Gatsby's own gatsby-image
(truthfully, I pilfered most of their excellent work and adapted it ; ).

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 being usable as a container (no more hacks with extra wrappers).

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

And it's even styleable with styled-components and the like!
(planned are media-queries: see TODO)

Example Repo

gatsby-background-image now has an example repository,
to see it's similarities & differences to gatsby-image side by side.
It's located at: gbitest

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. To produce perfect background-images, you need only:

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

The GraphQL query creates multiple thumbnails with optimized JPEG and PNG compression. The gatsby-background-image component automatically sets up the "blur-up" effect as well as lazy loading of images further down the screen.

Install

npm install --save gatsby-background-image

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

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`,
  ],
}

Important:

If you support Safari and/or Internet Explorer, you have to install several polyfills. Both need the IntersectionObserver polyfill, and IE also needs the Object-fit/Object-position one. As - at the time of writing - neither fully implements the former feature, and IE doesn't implement the latter.

A solution to this issue was mentioned in a comment over at gatsby-image/issues

How to use

This is what a component using gatsby-background-image looks like:

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

import BackgroundImage from 'gatsby-background-image'

const BackgroundSection = ({ className }) => (
    <StaticQuery query={graphql`
      query {
        desktop: file(relativePath: { eq: "seamless-bg-desktop.jpg" }) {
          childImageSharp {
            fluid(quality: 100, maxWidth: 4160) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
      }
    `}
     render={data => {
       // Set ImageData.
       const imageData = data.desktop.childImageSharp.fluid
       return (
          <BackgroundImage Tag="section"
                           className={className}
                           fluid={imageData}
                           backgroundColor={`#040e18`}
          >
            <h1>Hello gatsby-background-image</h1>
          </BackgroundImage>
       )
     }
     }
    />
)

const StyledBackgroundSection = styled(BackgroundSection)`
  width: 100%;
  background-repeat: repeat-y;
`

export default StyledBackgroundSection

Configuration & props

gatsby-background-image nearly works the same as gatsby-image so have a look at their options & props to get started.

gatsby-background-image has an added classId (as we have to name pseudo-elements and introduce a className for the returned container):

Name	Type	Description
`classId`	`string`	classID of the container element, defaults to a random lower case string of seven chars

Additionally, you are able to style your component with styled-components or your CSS-in-JS "framework" of choice. It should work with CSS, too, you just have to target the BackgroundImage-component's class:

.gatsby-background-image-[YOUR_ID]/*(:before, :after)*/ {
   background-repeat: repeat-y;
}

props not available

As gatsby-background-image doesn't use placeholder-images, the following two props from gatsby-image are of course not available (at the moment).

Name	Type	Old Usage
`placeholderStyle`	`object`	Spread into the default styles of the placeholder img element
`placeholderClassName`	`string`	A class that is passed to the placeholder img element

Troubleshooting

TODO

add Media-Query support

einarbirgir/gatsby-background-image