Using the beta Gatsby Image plugin
Adding responsive images to your site while maintaining high performance scores can be difficult to do manually. The Gatsby Image plugin handles the hard parts of producing images in multiple sizes and formats for you!
Want to learn more about image optimization challenges? Read the Conceptual Guide: Why Gatsby’s Automatic Image Optimizations Matter. For full documentation on all configuration options, see the reference guide.
The new Gatsby Image plugin is currently in beta, but you can try it out now and see what it can do for the performance of your site.
First you need to install the following packages:
You then need to add the plugins to your
If you already have some of these plugins installed, please check that they’re updated to the latest version.
The Gatsby Image plugin includes two image components: one for static and one for dynamic images. The simplest way to decide which you need to is to ask yourself: “will this image be the same every time the component or template is used?”. If it will always be the same, then use
StaticImage. If it will change, whether through data coming from a CMS or different values passed to a component each time you use it, then it is a dynamic image and you should use the
If you are using an image that will be the same each time the component is used, such as a logo or front page hero image, you can use the
StaticImage component. The image can be either a local file in your project, or an image hosted on a remote server. Any remote images are downloaded and resized at build time.
Add the image to your project.
If you are using a local image, copy it into the project. A folder such as
src/imagesis a good choice.
StaticImagecomponent to your template.
Import the component, then set the
srcprop to point to the image you added earlier. The path is relative to the source file itself. If your component file was
src/components/dino.js, then you would load the image like this:
If you are using a remote image, pass the image URL in the
When you build your site, the
StaticImagecomponent will load the image from your filesystem or from the remote URL, and it will generate all the sizes and formats that you need to support a responsive image.
Because the image is loaded at build time, you cannot pass the filename in as a prop, or otherwise generate it outside of the component. It should either be a static string, or a local variable in the component’s scope.
Important: Remote images are downloaded and resized at build time. If the image is changed on the other server, it will not be updated on your site until you rebuild.
Configure the image.
You configure the image by passing props to the
<StaticImage />component. You can change the size and layout, as well as settings such as the type of placeholder used when lazy loading. There are also advanced image processing options available. You can find the full list of options in the API docs.
This component renders a 200px by 200px image of a dinosaur. Before loading it will have a blurred, low-resolution placeholder. It uses the
"fixed"layout, which means the image does not resize with its container.
Note: There are a few technical restrictions to the way you can pass props into StaticImage. For more information, refer to the Reference Guide: Gatsby Image plugin. 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.
If you need to have dynamic images (such as if they are coming from a CMS), you can load them via GraphQL and display them using the
Add the image to your page query.
Any GraphQL File object that includes an image will have a
childImageSharpfield that you can use to query the image data. The exact data structure will vary according to your data source, but the syntax is like this:
Configure your image.
You configure the image by passing arguments to the
gatsbyImageDataresolver. You can change the size and layout, as well as settings such as the type of placeholder used when lazy loading. There are also advanced image processing options available. You can find the full list of options in the API docs.
Display the image.
You can then use the
GatbsyImagecomponent to display the image on the page. The
getImage()function is an optional helper to make your code easier to read. It takes a
file.childImageSharp.gatsbyImageData, which can be passed to the
If your site uses the old
gatsby-image component, you can use a codemod to help you migrate to the new Gatsby Image components. This can update the code for most sites. To use the codemod, run this command in the root of your site:
This will convert all GraphQL queries and components to use the new plugin. For more information see the full migration guide.