g(atsby-background-)image-bridge

Bringing gatsby-background-image to Gatsby 3!

g(atsby-background-)image-bridge bridges the gap between Gatsby 3+4's
gatsby-plugin-image syntax of providing images and the old
fluid / fixed syntax currently still used by
gatsby-background-image
& the now deprecated gatsby-image.

Don't know what I'm talking about? Head over to
Migrating from gatsby-image to gatsby-plugin-image
to see for yourself what changed in Gatsby 3 under the hood!

Table of Contents

- Install
- How to Use
- convertToBgImage()
- Contributing

Install

To add gbimage-bridge as a dependency to your Gatsby-project use

``bash
yarn add gbimage-bridge
`

or

`bash
npm install --save gbimage-bridge
`

You will need gatsby-background-image & have gatsby-plugin-image installed
as well. For gatsby-background-image installation instructions head over to
its README.
For installation instructions of gatsby-plugin-image, follow the
aforementioned migration guide.




Support for older browsers

If you want to use gbimage-bridge with gatsby-background-image-es5 you have to install all three packages.
Additionally, make sure you have core-js as a dependency in your package.json.

`bash
yarn add gbimage-bridge gatsby-background-image gatsby-background-image-es5 core-js
``

or

`bash
npm install --save gbimage-bridge gatsby-background-image gatsby-background-image-es5 core-js
``

Add import core-js/stable to the component using gbimage-bridge and Gatsby will automatically add
the needed polyfills.




How to use

For your convenience this package exports a Wrapper around BackgroundImage,
that automatically converts the new image format to the old one needed by it.
All properties are passed through to BackgroundImage so use BgImage like a
drop in replacement for it.
Read below what happens inside, but here's the wrapper:

`jsx
import { graphql, useStaticQuery } from 'gatsby';
import { getImage } from 'gatsby-plugin-image';
import { BgImage } from 'gbimage-bridge';

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

);
const pluginImage = getImage(image);

return (





);
};
`

It of course works with stacked images...

`jsx
import { graphql, useStaticQuery } from 'gatsby';
import { getImage } from 'gatsby-plugin-image';
import { BgImage } from 'gbimage-bridge';

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

);
const pluginImage = getImage(image);

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

return (





);
};
`

... and art-directed ones as well : )!

`jsx
import { graphql, useStaticQuery } from 'gatsby';
import { getImage } from 'gatsby-plugin-image';
import { BgImage } from 'gbimage-bridge';

const ArtDirectedBridgeTest = () => {
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 = [
...getImage(mobileImage),
{
...getImage(desktopImage),
media: (min-width: 491px),
},
];

return (





);
};
`

$3

Inside the Wrapper the following "magic" happens:

`jsx
// Convert it to the old format.
const bgImage = convertToBgImage(pluginImage);
`

convertToBgImage() takes an image of the form IGatsbyImageData (the result
from the new query). It then goes through the contents & extracts the necessary
images & remaining fields needed. You can of course use the result of the
function for the classic gatsby-image` as well!

Contributing

Everyone is more than welcome to contribute to this little package!
Docs, Reviews, Testing, Code - whatever you want to add, just go for it : ).
So have a look at our CONTRIBUTING file and give it a go.
Thanks in advance!