gatsby-background-image

Speedy, optimized background-images without the work!

gatsby-background-image is a React component which for background-images
provides, what Gatsby's own gatsby-(plugin)-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-(plugin)-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!**_

ES5 Version

gatsby-background-image has a companion package completely transpiled to
ES5: gatsby-background-image-es5.
Have a look at its README,
it nearly works the same - though with (nearly) all polyfills
included to support legacy browsers it's nearly three times the size of
this package.

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
- How to Use with Art-Direction support
- 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

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 optimized background-images, you need only to:

1. Import gatsby-background-image 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.

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 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 as a dependency to your Gatsby-project use

``bash
npm install --save gatsby-background-image
`

or

`bash
yarn add 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.

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

or

`bash
yarn add gatsby-transformer-sharp gatsby-plugin-sharp
`

Then in your gatsby-config.js:

`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:

`js
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:

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

#### Important:

If you support _Safari_ (older versions) and/or _Internet Explorer_, you have to
install the IntersectionObserver polyfill.
As - at the time of writing - neither fully implements the feature
(see caniuse.com).

A solution to this issue was mentioned in a comment over at gatsby-image/issues
and you are able to apply it the following way:

1. Install the intersection-observer
polyfill package by running:

`bash
npm i --save intersection-observer
`

or

`bash
yarn add intersection-observer
`

2. Dynamically load the polyfill in your gatsby-browser.js:

`js
// ES5 way
// exports.onClientEntry = () => {
// ES6 way
export const onClientEntry = () => {
// IntersectionObserver polyfill for gatsby-background-image (Safari, IE)
if (!(IntersectionObserver in window)) {
import(intersection-observer)
console.log(# IntersectionObserver is polyfilled!)
}
}
`

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:

`bash
yarn add gbimage-bridge
`

or

`bash
npm install --save gbimage-bridge
`

and usage with BackgroundImage is as follows:

`jsx
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 (
Tag="section"
// Spread bgImage into BackgroundImage:
{...bgImage}
preserveStackingContext
>




)
}
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 might look like:

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

import BackgroundImage from 'gatsby-background-image'

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 (
Tag="section"
className={className}
fluid={imageData}
backgroundColor={#040e18}
>


gatsby-background-image

)
}

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:

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

import BackgroundImage from 'gatsby-background-image'

const BackgroundSection = ({ className }) => (
query={graphql
query {
desktop: file(relativePath: { eq: "seamless-bg-desktop.jpg" }) {
childImageSharp {
fluid(quality: 90, maxWidth: 1920) {
...GatsbyImageSharpFluid_withWebp
}
}
}
}
}
render={data => {
// Set ImageData.
const imageData = data.desktop.childImageSharp.fluid
return (
Tag="section"
className={className}
fluid={imageData}
backgroundColor={#040e18}
>


gatsby-background-image

)
}}
/>
)

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 it might look like:

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

import BackgroundImage from 'gatsby-background-image'

const MultiBackground = ({ 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 (
Tag={section}
id={test}
className={className}
fluid={backgroundFluidImageStack}
>




This is a test of multiple background images.


)
}

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 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!

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

import BackgroundImage from 'gatsby-background-image'

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 (
Tag={section}
id={media-test}
className={className}
fluid={sources}
>



Hello art-directed gatsby-background-image.

)
}

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 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 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:

| Name | Default Value |
| --------------------- | ------------- |
| background-position | center |
| background-repeat | no-repeat |
| background-size | cover |

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:

`js
// 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:

`js
return dark : light} />
`

#### 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