Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Images and Performance

StaticImage: Optimized Images Without GraphQL

Use the StaticImage component from gatsby-plugin-image to resize, convert and lazy-load local or remote images at build time, with props explained.

Images are usually the heaviest part of a web page. A 4000-pixel photo straight from a camera can be several megabytes, and a phone with a 390-pixel-wide screen downloads all of it just to shrink it down. Gatsby's image tooling fixes this at build time: it resizes the picture, converts it to modern formats, writes several sizes, and generates the <img> markup the browser needs to pick the right one.

The simplest entry point is the StaticImage component from gatsby-plugin-image. "Static" means the image path is known when you write the code, so no GraphQL query is needed. In this lesson you will see how to use it, what its props do, and why they must be literal values.

Setting up

Three packages work together. gatsby-plugin-image provides the React components. gatsby-plugin-sharp and gatsby-transformer-sharp do the actual processing with the native sharp library. Add them in gatsby-config.js:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
module.exports = {
  plugins: [
    "gatsby-plugin-image",
    "gatsby-plugin-sharp",
    "gatsby-transformer-sharp",
  ],
}

The second and third plugins are shared with the dynamic image workflow you will meet in Dynamic images with GatsbyImage.

Your first StaticImage

JSX
// src/pages/index.js (real Gatsby, read-only)
import * as React from "react"
import { StaticImage } from "gatsby-plugin-image"

export default function Home() {
  return (
    <main>
      <h1>Hello</h1>
      <StaticImage
        src="../images/team.jpg"
        alt="Four people around a whiteboard"
        width={800}
        placeholder="blurred"
        formats={["auto", "webp", "avif"]}
      />
    </main>
  )
}

At build time Gatsby reads team.jpg, makes copies at several widths in JPEG, WebP and AVIF, and replaces the component with a <picture> element. The page also ships a tiny blurred preview that shows while the full image loads. src can be a relative file path or an absolute https:// URL; remote files are downloaded during the build and cached.

The most useful props

Prop What it does
src Path or URL of the source image (required).
alt Text for screen readers; use "" for purely decorative images.
layout constrained (default), fixed or fullWidth.
width / height Output size in CSS pixels. One dimension keeps the aspect ratio.
aspectRatio Crop to a ratio such as 16/9.
placeholder dominantColor, blurred, tracedSVG or none.
formats A list from auto, webp, avif, png, jpg.
quality 1-100, default 50.
loading lazy (default) or eager. Use eager for the hero image.
transformOptions Extra sharp options such as { fit: "cover", cropFocus: "attention" }.

The three layouts behave differently. Constrained scales down on small screens but never exceeds the width you set. Fixed is always exactly that size (good for logos and avatars). Full width stretches to the container.

Props of StaticImage must be literal values. You cannot write src={props.photo} or width={size}. Gatsby extracts the props with a static analysis step during the build, long before your component runs, so a variable gives an error. If the image depends on data, use GatsbyImage with a query instead.

Why it avoids layout shift

Before the image downloads, the browser needs to know how much room to reserve, otherwise the text below jumps when the picture appears. StaticImage renders a wrapper with the right aspect ratio, so the space is reserved. The next stand-in shows the arithmetic: a wrapper padding-bottom percentage equals height divided by width.

JS Stand-in: reserving space for an image

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What a build produces

Imagine one source image and the default outputPixelDensities. For a constrained image 800 pixels wide, Gatsby creates widths for 1x and 2x screens (and in between). The stand-in below imitates that list so you can see how a srcset is built.

JS Stand-in: a srcset for a constrained image

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line shows an important rule: Gatsby never upscales. A 900-pixel source gives no 1600-pixel file, because that would only add bytes, not detail.

Common mistakes

  • Passing a variable to a prop (see the warning above).
  • Forgetting alt. It is required for accessibility and the plugin warns about it.
  • Using loading="lazy" on the hero image at the top of the page. Lazy loading delays the largest contentful paint; set loading="eager" there.
  • Setting quality to 100. It makes files large for no visible gain; the default of 50 is usually enough for webp and avif.
  • Expecting StaticImage to work in a component where the source depends on a prop.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can't you pass src={props.photo} to StaticImage?

    The build step extracts the props before your component runs, so it cannot know a variable's value.
  2. 2. Which layout keeps an image at exactly the size you set, even on wide screens?

    Fixed output is always the given size. Constrained only caps the size, and fullWidth stretches.
  3. 3. What should you do for the large hero image at the top of a page?

    Eager loading avoids delaying the largest contentful paint.
  4. 4. Will Gatsby create a 1600 px file from a 900 px source?

    Sizes larger than the source are skipped because upscaling adds bytes but no detail.

Summary

  • StaticImage processes an image at build time and outputs a responsive, lazy-loaded <picture>.
  • You need gatsby-plugin-image, gatsby-plugin-sharp and gatsby-transformer-sharp.
  • Props must be literal values; use GatsbyImage for data-driven images.
  • Layouts are constrained, fixed and fullWidth; the wrapper reserves space to avoid layout shift.
  • Use loading="eager" for the first big image and keep alt meaningful.

Next: Dynamic images with GatsbyImage