Gatsby Image plugin

This guide will show you how to configure your images, including choosing layouts, placeholders and image processing options. While most of these options are available regardless of where you source your images, be sure to refer to the documentation of your source plugin if you are using images from a CMS, as the exact options are likely to vary.

Components

The Gatsby Image plugin includes two components to display responsive images on your site. One is used for static and the other for 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.

StaticImage

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

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.

Using StaticImage with CSS-in-JS libraries

The StaticImage component does not support higher-order components, which includes the styled function from libraries such as Emotion and styled-components. The parser relies on being able to identify StaticImage components in the source, and passing them to a function means this is not possible.

If you use Emotion you can use the provided css prop instead:

Unfortunately the css prop from styled-components turns the code into a styled function under the hood and as explained above StaticImage doesn’t support that syntax.

You can also use a regular style or className prop. Note that in all of these cases the styling is applied to the wrapper, not the image itself. If you need to style the <img> tag, you can use imgStyle or imgClassName. The className or imgClassName prop is helpful if your styling library is giving you a computed class name string instead of the computed styles (e.g. if you use libraries like linaria).

GatsbyImage

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 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 upper case by convention and is not quoted like a string. Both syntaxes are shown in the reference below.

Important: For dynamic images, these options are for the gatsbyImageData resolver on sharp nodes. If you are using gatsbyImageData from a different plugin, such as a CMS or image host, you should refer to that plugin’s documentation for the options, as they will differ from these. Static images use sharp under the hood, so these options apply when using the StaticImage component too.

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 browser.

Both static and dynamic images have the following options available:

See all options.

layout

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.

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:

width/height

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.

aspectRatio

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.

placeholder

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):

formats

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.

transformOptions

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.

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.

Customizing the default options

You might find yourself using the same options (like placeholder, formats etc.) with most of your GatsbyImage and StaticImage instances. You can customize the default options with gatsby-plugin-sharp.

The following configuration describes the options that can be customized along with their default values:

Helper functions

There are a number of utility functions to help you work with gatsbyImageData objects. We strongly recommend that you do not try to access the internals of these objects directly, as the format could change.

getImage

Safely get a gatsbyImageData object. It accepts several different sorts of objects, and is null-safe, returning undefined if the object passed, or any intermediate children are undefined.

If passed a File object, it will return file?.childImageSharp?.gatsbyImageData. If passed a node such as a ContentfulAsset that includes a gatsbyImageData field, it will return the gatsbyImageData object. If passed a gatsbyImageData object itself, it will return the same object.

getSrc

Get the default image src as a string. This will be the fallback, so usually jpg or png. Accepts the same types as getImage.

getSrcSet

Get the default image srcset. This will be the fallback, so usually jpg or png.

withArtDirection

By default, the plugin displays different image resolutions at different screen sizes, but it also supports art direction, which is where a visually-different image is displayed at different sizes. This could include displaying a simplified logo or a tighter crop on a profile picture when viewing on a small screen. To do this, you can use the withArtDirection function. You need both images available from GraphQL, and you should be able to write a media query for each size.

The first argument is the default image. This is displayed when no media queries match, but it is also used to set the layout, size, placeholder and most other options. You then pass an array of “art directed images” which are objects with media and image values.

When the screen is less than 1024px wide, it will display smallImage. Otherwise, it will display largeImage.

The aspect ratio is set by the default image, and doesn’t automatically change with the different sources. The way to handle this is to use CSS media queries. For example, you could use this CSS to change the size of the container in small images:

You can then apply this using plain CSS, or the styling system of your choice. e.g.