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
To add gbimage-bridge
as a dependency to your Gatsby-project use
yarn add gbimage-bridge
or
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
.
yarn add gbimage-bridge gatsby-background-image gatsby-background-image-es5 core-js`
or
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:
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 (
<BgImage image={pluginImage} style={{ minWidth: 200, minHeight: 200 }}>
<div>Hello from BgImage!</div>
</BgImage>
);
};
It of course works with stacked images...
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 (
<BgImage image={backgroundFluidImageStack} style={{ minWidth: 200, minHeight: 200 }}>
<div>Hello from BgImage!</div>
</BgImage>
);
};
... and art-directed ones as well : )!
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 (
<BgImage image={sources} style={{ minWidth: 200, minHeight: 200 }}>
<div>Hello from BgImage!</div>
</BgImage>
);
};
convertToBgImage()
Inside the Wrapper the following "magic" happens:
// 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!