Fix Image Layout Shift in Gatsby with gatsby-plugin-image

Images Keep Pushing Your Content Around

A hero image that loads after the surrounding text can shove paragraphs down the page, hurting Cumulative Layout Shift and frustrating readers. In Gatsby, plain <img> tags or unoptimized assets often arrive without reserved dimensions, so the browser reflows once the file finishes downloading.

What gatsby-plugin-image Reserves at Build Time

The plugin processes images with Sharp during gatsby build, then emits HTML that includes srcset, sizes, and an inline base64 placeholder. Because the placeholder carries aspect-ratio information, the browser can reserve the correct space before the full image arrives.

Worked Example: A Constrained Hero Image

Install and configure

Run this in the project root:

npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp

Add the plugins to gatsby-config.js:

module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
  ],
}

Use StaticImage with explicit layout

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

export default function Home() {
  return (
    
  )
}

layout="constrained" tells Gatsby to preserve the aspect ratio while scaling within the parent container. At build time, Sharp generates several widths and modern formats, and the rendered markup includes a low-resolution placeholder that occupies the same box as the final image.

Verify the generated markup

• Run gatsby build and open public/index.html.
• Look for an <img> tag with srcset, sizes, and loading="lazy".
• Open Chrome DevTools, go to Network, reload the page, and confirm the browser requests a WebP or AVIF variant before the fallback JPEG.
• Run Lighthouse and check that Cumulative Layout Shift and Largest Contentful Paint improve after the change.

Trade-Offs to Watch

• Build time: Every image size and format multiplies Sharp processing. Large libraries can add minutes; use Gatsby's cache or incremental builds to keep deploys predictable.
• Lazy-loading conflicts: The default loading="lazy" can delay images that your scroll animations reveal immediately. Override with loading="eager" for above-the-fold assets.
• Format support: AVIF and WebP are not universal. Gatsby falls back to JPEG or PNG automatically, but verify your target browsers if you restrict the formats prop.

Make the Change Before the Next Deploy

1. Search your pages for bare <img> tags pointing to local assets.
2. Replace them with StaticImage for source-tree images or GatsbyImage for CMS-driven data.
3. Set explicit width and height or use layout="constrained" so the browser reserves space early.
4. Audit with Lighthouse after the build, then tune quality and maxWidth if build times grow.