Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Images and Performance

Image Formats, Layouts and Placeholders

Choose between WebP, AVIF and JPEG, constrained, fixed and full-width layouts, and blurred or dominant-color placeholders to balance speed and quality.

You now know how to render an optimized image. This lesson explains the choices behind the settings, so you can pick them deliberately rather than copying defaults. Three decisions matter: the file format, the layout (how the image scales) and the placeholder (what shows while loading). A fourth, quality, trades file size against detail.

File formats

Browsers support several image formats, each with a sweet spot.

Format Best for Notes
JPEG Photos Universal support, the safe fallback.
PNG Sharp graphics, transparency Large for photos.
WebP Photos and graphics Usually 25-35% smaller than JPEG. Supported by all current browsers.
AVIF Photos Often the smallest, slower to encode at build time.
SVG Logos, icons Vector, not processed by sharp; import it as a file or component.

The formats option takes a list. AUTO means "the original format" (JPEG for a JPEG source), which acts as the fallback. A typical setting is [AUTO, WEBP, AVIF]. Gatsby writes a <picture> element with one <source> per format, ordered best first, and the browser uses the first one it understands.

JSX
// real Gatsby, read-only
<StaticImage
  src="../images/city.jpg"
  alt="City skyline at dusk"
  formats={["auto", "webp", "avif"]}
/>

More formats means more files and a longer build. For a site with thousands of images, start with [AUTO, WEBP] and add AVIF only where it matters (hero images).

Layouts

layout decides what sizes are generated and how CSS scales the image.

  • constrained: you give a width (the maximum). Gatsby generates 1x and 2x versions. The image shrinks in narrow containers, never grows past width.
  • fixed: always exactly width by height CSS pixels. Generates 1x and 2x for sharp displays.
  • fullWidth: fills its container; many widths are generated from breakpoints (the defaults range from 750 to 3840).

Pick fixed for avatars and logos, constrained for content images, and fullWidth for banners. Remember that sizes and breakpoints only matter for the responsive layouts.

JS Stand-in: which widths each layout generates

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

No output.

The final line shows the same no-upscaling rule you saw earlier.

Placeholders

While the real image downloads, the area can show something. The placeholder option chooses what.

  • dominantColor: a flat color computed from the image. Tiny (a few bytes) and instant.
  • blurred: a 20 pixel wide copy embedded as a base64 string and blurred by CSS. Looks the most polished, adds about 1 KB to the HTML.
  • tracedSVG: a vector trace, for graphics with clear shapes; slower to build.
  • none: nothing (a transparent box). Use it for above-the-fold images that will load almost instantly.

The dominant color is simply an average of pixels. This stand-in computes it from a small grid of RGB values:

JS Stand-in: a dominant color

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

No output.

Quality and file size

The quality option runs from 1 to 100. The default is 50 for the generated formats, which is intentionally lower than camera defaults, because modern codecs look good at that level. Raise it for photographs where banding appears, lower it for decorative backgrounds. Always judge by looking at the output, not the number.

You can also change defaults for the whole site in the plugin options:

JavaScript
// gatsby-config.js (real Gatsby, read-only)
{
  resolve: "gatsby-plugin-sharp",
  options: {
    defaults: { formats: ["auto", "webp"], placeholder: "blurred", quality: 60, breakpoints: [750, 1080, 1366, 1920] },
  },
}

Individual components then only override what differs.

Large source files

Sharp needs memory for big images. Resize camera originals to a maximum of about 3000 pixels before committing them. This speeds up every build, and the extra pixels would never be used anyway because of the no-upscaling rule. Also use .gitattributes or Git LFS if you keep many large originals in the repository.

Common mistakes

  • Using PNG for photographs: always let AUTO or webp handle photos.
  • Forgetting a fallback format: formats={["webp"]} alone leaves old browsers without an image.
  • Using fullWidth for small thumbnails, which generates large files nobody needs.
  • Putting an SVG through StaticImage; import SVG files directly instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the AUTO format mean in formats?

    AUTO keeps the original format (for example JPEG) so every browser has something to show.
  2. 2. Which layout is the best choice for a 96 px user avatar?

    An avatar has a fixed size, so fixed generates only 1x and 2x files.
  3. 3. Which placeholder embeds a tiny blurred copy of the image?

    blurred embeds a very small base64 image that CSS blurs.
  4. 4. Why resize camera originals before adding them to the repo?

    Extra pixels cost build time and memory but never reach visitors.

Summary

  • List formats as [AUTO, WEBP, AVIF]; the browser picks the first it supports.
  • constrained, fixed and fullWidth generate different sets of widths.
  • Placeholders trade a few bytes for a smoother loading experience.
  • Keep quality moderate and set site-wide defaults in gatsby-plugin-sharp.
  • Never upscale and keep source files a sensible size.

Next: Performance, Lighthouse and prefetching