Migrating from gatsby-image to gatsby-plugin-image
This document is provided to help users of
gatsby-image migrate to using
Note that you can use both packages at the same time. You may need to in situations where you’re using a
gatsby-image-compatible CMS as a data source, and that CMS plugin has not yet updated to a version compatible with the new API.
If you’re looking for other documentation on the new plugin, see:
- How-To Guide: Using the beta Gatsby Image plugin
- Reference Guide: Gatsby Image plugin
The new plugin requires significant syntax changes. We’ve provided a codemod to help you migrate, but this section will explain the changes.
GatsbyImage was the default export from
gatsby-plugin-image, the component is now a named export.
This is one of the bigger changes. There are no more fragments to use. Instead, things like
format are passed as arguments to the resolver.
This is the previous syntax.
The new syntax looks like this. The fragment is removed in favor of
gatsbyImageData, which is used for all images. Previous configuration options - such as
fluid, WebP generation, and placeholder type - are passed as arguments to the resolver.
Other changes to the available argument structure are in the section on API changes.
The last change is to the JSX component. The import name is potentially different, and the query result is also different.
In addition to the syntax changes for using
gatsby-plugin-image, there are also changes to the API that affect the resolver arguments (and the new
fluid image type has been deprecated in favor of two alternatives.
The first is an image type called
fullWidth. This image is designed to be used for things like hero images that span the full width of the screen, and generates image sizes accordingly. Instead of passing something like
maxWidth, it takes an array called
breakpoints that will generate images designed for those screen sizes. In most cases you will not need to provide these, as there are default values that work for most sites. Note that like the old
fullWidth images will expand to fit the width of their container, even if that width is larger than the source image.
The second is a responsive image type called
constrained that will shrink with its container and generates smaller images, but nothing larger than the original image source size. Additionally, you can pass
height to limit the displayed image to that size. In this case, larger images may be generated for high-density screens.
maxHeight are deprecated for all image types. For
fixed images, use
fullWidth images, look at the
aspectRatio is a new argument that takes a number (or fraction). If you pass it without also passing in
height, it will default to using the source image width and then adjusting the height to the correct aspect ratio. Alternatively, you can pass your own
height and it will set the other dimension. Passing both
width will cause
aspectRatio to be ignored in favor of the inferred aspect ratio.
Previously, images generated their own type by default, e.g. JPG, PNG, etc. You could also generate WebP images when using the appropriate fragment. This is now controlled using the
formats argument. This field takes an array,
[AUTO, WEBP] by default, where
AUTO means the same format as the source image.
AVIF is now also a valid format.
Options nested inside objects
Previously, transformations like
grayscale and quality options such as
pngQuality were top level query arguments. This has changed.
grayscale now exists within the
transformOptions argument, and
pngOptions. See the
gatsby-plugin-image Reference Guide for specifics.
Due to the changes to
gatsby-plugin-image, there is some functionality that is no longer supported.
GatsbyImageis no longer a class component and therefore cannot be extended. You can use composition instead.
fluidimages no longer exist, and the
fullWidthreplacement does not take
The art direction API has changed, see the
gatsby-plugin-imagereference guide for specifics.
The component no longer takes a decomposed object, and the following code is not valid. You should avoid accessing or changing the contents of the
gatsbyImageDataobject, as it is not considered to be a public API, so can be changed without notice.
How to Migrate
Install and update dependencies.
Run the codemod.
Note that if you need to do a partial migration, e.g. because you’re using a CMS that doesn’t yet support the new plugin alongside local image files, you’ll want to make use of the
optional-pathto run against individual files.
optional-path, the codemod will run against all the files in your current directory, so running it in root is recommended. It will ignore
publicautomatically. It will also respect any local Babel configuration in your project. The codemod is designed to run against files with the extensions
.jsx. If this does not cover your project, or you require other customizations, see the section on using
Due to the API changes, the codemod is not a pure 1:1 mapping. There are some changes introduced.
Fluid images will map to either
constrainedimages. This decision is made based on the existence of
maxWidthand its value. If
maxWidthdoes not exist, it will be a
fullWidthimage. If it does, and the
maxWidthis less than 1000, it will be a
constrainedimage, otherwise a
fullWidthimages do not retain their
constrainedimages do, as
All images will generate WebP.
The codemod will output warnings in a number of different scenarios and point you to the file in question so you can inspect the changes manually.
Consider manual changes.
For images using static query, you should move to use the
StaticImagecomponent instead. This component takes
src, which can be a remote image URL or a relative path to an image. Make sure you’ve installed
gatsby-source-filesystemif you’re going to use this component.
You may also consider refactoring code to make use of the
Finally, if you were previously using
src, e.g. for an SEO component, you’ll want to use the
getSrchelper function as the internal structure of the return object has changed.
This section is for people who need to run the codemod with extra flags exposed by
jscodeshift, e.g. to transform file types other than those with extensions
- Install the codemods package in your project.
- Run the codemod using
See the jscodeshift docs for all the available flags.