Gatsby Image plugin

This guide will show you how to configure your images, including choosing layouts, placeholders and image processing options.


The Gatsby Image plugin includes two components to display responsive images on your site, used for static and dynamic images.

  • StaticImage: Use this if the image is the same every time the component is used. Examples: site logo, index page hero image
  • GatsbyImage: Use this if the image is passed into the component as a prop, or otherwise changes. Examples: Blog post hero image, author avatar

If you would like to learn how to set up the image plugins and use these components on your site, see the how-to guide.

These are props that can be passed to the components:

Shared props

The following props can be passed to both GatsbyImage and StaticImage. You may also use any valid <img> tag props, which are forwarded to the underlying <img> element.

alt (Required)stringAlternative text, passed to the <img> tag. Required for accessibility.
asElementType"div"The HTML element used for the outer wrapper.
loading"eager" ∣ "lazy""lazy"Loading behavior for the image. You should set this to "eager" for above-the-fold images to ensure they start loading before React hydration.
classNamestringCSS class applied to the outer wrapper.
imgClassNamestringCSS class applied to the <img> element.
styleCSSPropertiesInline styles applied to the outer wrapper.
imgStyleCSSPropertiesInline styles applied to the <img> element.
backgroundColorstringtransparentBackground color applied to the wrapper.
objectFitSee MDN doccoverResizing behavior for the image within its container.
objectPositionSee MDN doc50% 50%Position of the image within its container.


The StaticImage component can take all image options as props, as well as all shared props. Additionally, it takes this prop:

src (Required)stringSource image, processed at build time. Can be a path relative to the source file, or an absolute URL.

Restrictions on using StaticImage

The images are loaded and processed at build time, so there are restrictions on how you pass props to the component. The values need to be statically-analyzed at build time, which means you can’t pass them as props from outside the component, or use the results of function calls, for example. You can either use static values, or variables within the component’s local scope. See the following examples:

This does not work:

…and nor does this:

You can use variables and expressions if they’re in the scope of the file, e.g.:

If you find yourself wishing you could use a prop for the image src then it’s likely that you should be using a dynamic image.


This component accepts all shared props, as well as the one below. These props are passed directly to the component, and are not to be confused with image options, which are passed to the GraphQL resolver when using dynamic images.

image (Required)GatsbyImageDataThe image data object, returned from the gatsbyImageData resolver.

Image options

There are a few differences between how you specify options for StaticImage and GatsbyImage:

  1. How to pass options: When using StaticImage, options are passed as props to the component, whereas for the GatsbyImage component they are passed to the gatsbyImageData GraphQL resolver.
  2. Option values: In the StaticImage component, props such as layout and placeholder take a string, while the resolver takes a a GraphQL enum, which is in upper case by convention and is not quoted like a string. Both syntaxes are shown in the reference below.

Note: It is a very good idea to use the GraphiQL IDE when writing your gatsbyImageData queries. It includes auto-complete and inline documentation for all of the options and lets you see the generated image data right inside the IDE.

Both static and dynamic images have the following options available:

OptionDefault string/enum valueDescription
layout"constrained" / CONSTRAINEDDetermines the size of the image and its resizing behavior.
aspectRatioSource image aspect ratioForce a specific ratio between the image’s width and height.
width/heightSource image sizeChange the size of the image.
placeholder"dominantColor"/DOMINANT_COLORChoose the style of temporary image shown while the full image loads.
formats["auto","webp"]/[AUTO,WEBP]File formats of the images generated.
transformOptions{fit: "cover", cropFocus: "attention"}/{fit: COVER, cropFocus: ATTENTION}Options to pass to sharp to control cropping and other image manipulations.

See all options.


The image components support three types of layout, which determine the image sizes that are generated, as well as the resizing behavior of the image itself in the browser.

LayoutComponent prop valueResolver prop valueDescription
Constrained"constrained"CONSTRAINEDThis is the default layout. It displays the image at the size of the source image, or you can set a maximum size by passing in width or height). If the screen or container size is less than the width of the image, it scales down to fit, maintaining its aspect ratio. It generates smaller versions of the image so that a mobile browser doesn’t need to load the full-size image.
Fixed"fixed"FIXEDThis is a fixed-size image. It will always display at the same size, and will not shrink to fit its container. This is either the size of the source image, or the size set by the width and height props. Only use this if you are certain that the container will never need to be narrower than the image.
Full width"fullWidth"FULL_WIDTHUse this for images that are always displayed at the full width of the screen, such as banners or hero images. Like the constrained layout, this resizes to fit the container. However it is not restricted to a maximum size, so will grow to fill the container however large it is, maintaining its aspect ratio. It generates several smaller image sizes for different screen breakpoints, so that the browser only needs to load one large enough to fit the screen. You can pass a breakpoints prop if you want to specify the sizes to use, though in most cases you can allow it to use the default.

You can compare the layouts in the video below:

To set the layout, pass in the type to the layout prop. e.g.

For a dynamic image, pass it to the resolver:


Layouts: fixed and constrained

Size props are optional in GatsbyImage and StaticImage. Because the images are processed at build time, the plugin knows the size of the source image and can add the correct width and height to the <img> tag, so it displays correctly with no layout jumping. However, if you want to change the display size you can use the size options to do this.

For a fixed layout, these define the size of the image displayed on screen. For a constrained image these define the maximum size, as the image will scale down to fit smaller containers if needed.

If you set just one of these, the source image is resized to that width or height while maintaining aspect ratio. If you include both then it is also cropped if needed to ensure it is that exact size.


Layouts: fixed, constrained, and fullWidth

The aspectRatio prop forces an image to the specified aspect ratio, cropping if needed. The value is a number, but can be clearer to express as a fraction, e.g. aspectRatio={16/9}

For fixed and constrained images, you can also optionally pass either a width or height, and it will use that to calculate the other dimension. For example, if you pass width={800} aspectRatio={4/3} then height will be set to the width divided by the aspect ratio: so 600. Passing 1 as the aspectRatio will crop the image to a square. If you don’t pass a width or height then it will use the source image’s width.

For fullWidth images you don’t specify width or height, as it resizes to fit the screen width. Passing aspectRatio will crop the image if needed, and the height will scale according to the width of the screen. For example, if you set the aspectRatio to 16/9 then when the image is displayed full width on a screen that is 1280px wide, the image will be 720 pixels high.

Note: There are several advanced options that you can pass to control the cropping and resizing behavior. For more details, see the transformOptions reference.


Gatsby image components are lazy-loaded by default, which means that if they are offscreen they are not loaded by the browser until they come into view. To ensure that the layout does not jump around, a placeholder is displayed before the image loads. You can choose one of three types of placeholder (or not use a placeholder at all):

PlaceholderComponent prop valueResolver prop valueDescription
Dominant color"dominantColor"DOMINANT_COLORThe default placeholder. This calculates the dominant color of the source image and uses it as a solid background color.
Blurred"blurred"BLURREDThis generates a very low-resolution version of the source image and displays it as a blurred background.
Traced SVG"tracedSVG"TRACED_SVGThis generates a simplified, flat SVG version of the source image, which it displays as a placeholder. This works well for images with simple shapes or that include transparency.
None"none"NONENo placeholder. You can use the background color option to set a static background if you wish.


Default component prop value: ["auto", "webp"]. Default resolver prop value: [AUTO, WEBP]

The Gatsby Image plugin supports four output formats: JPEG, PNG, WebP and AVIF. By default, the plugin generates images in the same format as the source image, as well as WebP. For example, if your source image is a PNG, it will generate PNG and WebP images. In most cases, you should not change this. However, in some cases you may need to manually set the formats. One reason for doing so is if you want to enable support for AVIF images. AVIF is a new image format that results in significantly smaller file sizes than alternative formats. It currently has limited browser support, but this is likely to increase. It is safe to include as long as you also generate fallbacks for other browsers, which the image plugin does automatically by default.


These values are passed in as an object to transformOptions, either as a prop to StaticImage, or to the resolver for dynamic images. They are advanced settings that most people will not need to change. Any provided object is merged with the defaults below.

Option nameDefaultDescription
grayscalefalseConvert image to grayscale
duotonefalseAdd duotone effect. Pass false, or options object containing {highlight: string, shadow: string, opacity: number}
rotate0Rotate the image. Value in degrees.
trimfalseTrim “boring” pixels. See the sharp documentation.
cropFocus"attention"/ATTENTIONControls crop behavior. See the sharp documentation for strategy, position and gravity.
fit"cover"/COVERControls behavior when resizing an image and proving both width and height. See the sharp documentation.

All options

The Gatsby Image plugin uses sharp for image processing, and supports passing through many advanced options, such as those affecting cropping behavior or image effects including grayscale or duotone, as well as options specific to each format.

layout"constrained" / CONSTRAINEDDetermines the size of the image and its resizing behavior.
width/heightSource image sizeChange the size of the image.
aspectRatioSource image aspect ratioForce a specific ratio between the image’s width and height.
placeholder"dominantColor"/DOMINANT_COLORChoose the style of temporary image shown while the full image loads.
formats["auto","webp"]/[AUTO,WEBP]File formats of the images generated.
transformOptions{fit: "cover", cropFocus: "attention"}Options to pass to sharp to control cropping and other image manipulations.
sizesGenerated automaticallyThe <img> sizes attribute, passed to the img tag. This describes the display size of the image, and does not affect generated images. You are only likely to need to change this if your are using full width images that do not span the full width of the screen.
quality50The default image quality generated. This is overridden by any format-specific options
outputPixelDensitiesFor fixed images: [1, 2]
For constrained: [0.25, 0.5, 1, 2]
A list of image pixel densities to generate. It will never generate images larger than the source, and will always include a 1x image. The value is multiplied by the image width, to give the generated sizes. For example, a 400 px wide constrained image would generate 100, 200, 400 and 800 px wide images by default. Ignored for full width layout images, which use breakpoints instead.
breakpoints[750, 1080, 1366, 1920]Output widths to generate for full width images. Default is to generate widths for common device resolutions. It will never generate an image larger than the source image. The browser will automatically choose the most appropriate.
blurredOptionsNoneOptions for the low-resolution placeholder image. Ignored unless placeholder is blurred.
tracedSVGOptionsNoneOptions for traced placeholder SVGs. See potrace options. Ignored unless placeholder is traced SVG.
jpgOptionsNoneOptions to pass to sharp when generating JPG images.
pngOptionsNoneOptions to pass to sharp when generating PNG images.
webpOptionsNoneOptions to pass to sharp when generating WebP images.
avifOptionsNoneOptions to pass to sharp when generating AVIF images.