Skip to main content

Using gatsby-image to prevent image bloat

gatsby-image is a React component designed to work seamlessly with Gatsby’s GraphQL queries (gatsby-image plugin READme). It combines Gatsby’s native image processing capabilities with advanced image loading techniques to easily and completely optimize image loading for your sites. gatsby-image uses gatsby-plugin-sharp to power its image transformations.

Warning: gatsby-image is not a drop-in replacement for <img />. It’s optimized for fixed width/height images and images that stretch the full-width of a container. Some ways you can use <img /> won’t work with gatsby-image.


gatsby-image includes the tricks you’d expect from a modern image component. It:

  • uses the new IntersectionObserver API to cheaply lazy load images
  • holds an image’s position so your page doesn’t jump around as images load
  • makes it easy to add a placeholder—either a gray background or a blurry version of the image.


Large, unoptimized images dramatically slow down your site.

But creating optimized images for websites has long been a thorny problem. Ideally you would:

  • Resize large images to the size needed by your design
  • Generate multiple smaller images so smartphones and tablets don’t download desktop-sized images
  • Strip all unnecessary metadata and optimize JPEG and PNG compression
  • Efficiently lazy load images to speed initial page load and save bandwidth
  • Use the “blur-up” technique or a ”traced placeholder” SVG to show a preview of the image while it loads
  • Hold the image position so your page doesn’t jump while images load

Doing this consistently across a site feels like sisyphean labor. You manually optimize your images and then… several images are swapped in at the last minute or a design-tweak shaves 100px of width off your images.

Most solutions involve a lot of manual labor and bookkeeping to ensure every image is optimized.

This isn’t ideal. Optimized images should be easy and the default.


With Gatsby, we can make images way way better.

gatsby-image is designed to work seamlessly with Gatsby’s native image processing capabilities powered by GraphQL and Sharp. To produce perfect images, you only need to:

  1. Import gatsby-image and use it in place of the built-in img
  2. Write a GraphQL query using one of the included GraphQL “fragments” which specify the fields needed by gatsby-image.

The GraphQL query creates multiple thumbnails with optimized JPEG and PNG compression. The gatsby-image component automatically sets up the “blur-up” effect as well as lazy loading of images further down the screen.

Here’s what a really simple Gatsby page component using gatsby-image would look like:

import React from "react"
import Img from "gatsby-image"

export default ({ data }) => (
    <h1>Hello gatsby-image</h1>
    <Img resolutions={data.file.childImageSharp.resolutions} />

So this is all very nice and it’s far better to be able to use this from NPM vs. implementing it yourself or cobbling together several standalone libraries.


edit this page on GitHub