Loving gatsby-plugin-image with Gatsby v3 πŸ’Œ

August 24, 2021

I have been using the new gatsby-plugin-image with Gatsby v3 on a recently started personal project.

And I love it ❀️‍πŸ”₯

True Love from Undraw

The first thing I noticed was the speed increase 🏎️

Optimizing images using gatsby-plugin-image becomes much, much easier.

In BETA release prior to when Gatsby v3 was shipped - and generally available since March 2021 - this plugin has a very straightforward API.

I have found working with it to be a great developer experience πŸ‘

The plugin comes with two different components, <StaticImage /> and a rewritten <GatsbyImage />.

There are also some helper functions - including getImage() and getSrc() - which are detailed thoroughly in the docs.

Both StaticImage and GatsbyImage components drastically reduce the β€œover-the-wire” size of images compared to using a simple <img> tag.

gatsby-image-plugin uses some brilliant abstractions to create source sets of your remote or local images. Just as with a regular <img> element - you similarly set an image with a src prop on your component. Various sizes and formats are created under the hood - in order to serve the most optimized version based on the client device and screen size.

More info about how this is accomplished can be found at the Gatsby Conceptual Guides.

The new plugin was designed to take advantage of the recent WebPImage standard as well as AVIF images - a brand new format used at Netflix, Google and several other large companies with gigantic websites. The AVIF format offers better sizes and quality over jpg or other standard file types.

The next thing I noticed were the customization options πŸ˜„

Props are added manually to the component in the case of <StaticImage />, and they are added dynamically through data gathered from a GraphQL query if using the <GatsbyImage /> option.

There is a long list of options to customize how your images render - including layout, aspectRatio, placeholder, formats, etc.

All prop options can be found at the Gatsby-Image resource guide.

Example from my recent project code:

  alt="A self portrait in a rocking chair"
  transformOptions={{ grayscale: true }}

The following is a GraphQL query that gathers some image nodes from a local folder:

export const data = graphql`
    allFile(filter: { sourceInstanceName: { eq: "instagram" } }) {
      nodes {
        childImageSharp {
          gatsbyImageData(height: 300, width: 300, layout: FIXED)

Which I then map over in a page component - to display like so:

// project styled using css modules
<div className={styles.picContainer}>
  {nodes.map(pic => {
    // calling helper function here
    const image = getImage(pic)
    return (

All code for this project can be found by clicking here πŸ€“

Lastly, to get up and running with these tools in your next Gatsby project, I recommend this excellent 10 minute video by Laurie Barth from a talk during GatsbyConf 2021.

Laurie concisely goes over the options available when working with gatsby-image-plugin. This video contains all the information I needed in order to get started using it initially.

And, ofcourse, the Gatsby docs are of very high quality πŸ₯‡

Happy coding with Gatsby v3!


Profile picture

A Programming Blog by John William Davis - Based in Seattle - I am interested in all things React, Node, Rust and Vim πŸ€“ Β  Follow me on Twitter Β βœ…