Gatsby 3 Image - A Deep-dive into the new image API features

Gatsby has been one of the favorite tools of developers to build fast, accessible, and feature-rich websites and web apps. The recent version of Gatsby i.e v3 brings some great features to an already awesome Web Framework. One of those features is improvements to its Image API. Now shipping as a separate plugin called, gatsby-plugin-image.

So, let's go ahead and check these features out.

New Image API

The new version of Gatsby introduces a brand new API to work with images. The new gatsby image API is simpler and easy to use and is designed to be able to easily adapt. It separates integrating dynamic and static images in the Site. Now the static images do not need to be queried with GraphQL making it much easier to work with, and querying dynamic images is now declarative and simpler.

To use the new API you need to install a separate package

npm install gatsby-plugin-image

After installation you can add the plugin in the gatsby-config.js and add the default configuration options.

// gatsby-config.js
module.exports = {
...
...
	`gatsby-plugin-image`,
	`gatsby-transformer-sharp`,
	{
    resolve: `gatsby-plugin-sharp`,
    options: {
      defaults: {
        formats: [`auto`, `webp`, `avif`],
        placeholder: `blurred`
        quality: 50
        breakpoints: [750, 1080, 1366, 1920]
        backgroundColor: `transparent`
        tracedSVGOptions: {}
        blurredOptions: {}
        jpgOptions: {}
        pngOptions: {}
        webpOptions: {}
        avifOptions: {}
      }
    }
  },
...
...
}

Static Images

In the new Gatsby image API, working with static images is much easier. Gatsby 3 provides a component called <StaticImage /> which can easily integrate images while taking advantage of Image optimization provided by gatsby.

import React from "react"
import { StaticImage } from "gatsby-plugin-image"

const MyComponent = () => (
  <section>
    <h2>Team</h2>
    <StaticImage
      src="../images/team.png"
      alt="Team Picture"
      layout="flexible"
      placeholder="blurred"
      width={400}
    />
  </section>
)

export default MyComponent

As you can see in the above example that makes it way easier to integrate images. All the options can be easily passed as props to the component. Although there are some limitations on how you can pass the props to this component. The props need to be fixed and cannot be changed later(at runtime). If you need to change the props or options later you can check the next part on how to integrate dynamic images in Gatsby 3.

Dynamic Images

The Image API in Gatsby 3 rebuilt to become simpler. Now you don't need to use weird queries or use GraphQL fragments to get different image formats. Now it looks like this.

import React from "react"
import { useStaticQuery, graphql } from "gatsby"
import { GatsbyImage } from "gatsby-plugin-image"

const imageQuery = graphql`
	userImage: file(relativePath: { eq: "user_01.png" }) {
    childImageSharp {
      gatsbyImageData(
        layout: FIXED
        width: 150
        height: 150
        placeholder: BLURRED
        formats: [AUTO, WEBP, AVIF]
      )
    }
  }
`

const UserProfile = () => {
  const data = useStaticQuery(imageQuery)

  return (
    <GatsbyImage
      image={userImage.childImageSharp.gatsbyImageData}
      alt="Team Meeting"
    />
  )
}

As you can see in the above example, now the Image API is declarative and very simple. The options can be passed as arguments. You just need to import the <GatsbyImage /> component and pass the GraphQL result directly to it.

Available Props and options

• layout - this prop defines layout style which can be fixed, constrained and fullWidth
• placeholder - Defines how to handle the placeholder for your image while it's being loaded. some options are blurred, travedSVG, dominantColor.
• formats - Defines what formats to convert the image. Can accept auto, webp and avif.
• aspectRatio - It is a new argument that takes a number or fraction. If you pass it without also passing in width or height, it will default to using the source image width and then adjusting the height to the correct aspect ratio.

New Image Formats(AVIF)

The new image API in Gatsby v3 also adds support for some of the newer image formats. Such as AVIF(AV1 Image Format), which is an open, royalty-free encoding format. AVIF has better compression efficiency than JPEG, and they perform even better than WebP images. Although currently it's only supported in Chrome, Opera, and Firefox(need to enable a flag). Microsoft Edge has a plugin for enabling AVIF Images and Safari has no support.

Incremental Generation and Performance Improvements 🚀

While you're using Gatsby 3 in development mode, it will only build pages or process images when your development server requests them. That means no need to build all the pages and process images in advance. That makes it incredibly fast and easy to work with and provides a better development experience overall.

Migration Guide

For now, the Gatsby v3 still works with the old image API. Although it'll give you warnings to upgrade to the newer version. and you won't be able to take advantage of some of the newer features. Some Gatsby Plugins have already moved to newer image API while some are still working on their version for Gatsby 3. You can refer to their Migration Guide for more details.

Hope you find this article useful and it helped you learn about the new image API in Gatsby 3. You can refer to the official website and Gatsby 3 guide to learn more about the specification, and how to migrate from older version.

Official Gatsby 3 Blog: Introducing Gatsby 3.0 – Faster in Every Way that Matters

Gatsby Plugin Image: gatsby-plugin-image

Official Migration Guide for Migrating to gatsby-plugin-image: Migrating from v2 to v3

Official Migration Guide for Gatsby: Migrating from v2 to v3

- Jitendra Nirnejak