Gatsby Plugin Image

Installation

Using the gatsby-plugin-image package requires installing a few packages. First, we need to install gatsby-plugin-image and gatsby-plugin-sharp.

npm install gatsby-plugin-image gatsby-plugin-sharp

If you plan on only using static images (images saved in your repository), install the gatsby-source-filesystem plugin as well.

npm install gatsby-source-filesystem

If you also want to use dynamic images (for example, images fetched from a content management system, meaning that images might change from time to time), install the gatsby-transformer-sharp plugin.

npm install gatsby-transformer-sharp

Next, we'll need to add the plugins in our gatsby-config.js file. Note that these might have already been added to the plugins array in gatsby-config.js , if you built your Gatsby project from a template like gatsby-starter-default.

// gatsby-config.js

module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-source-filesystem`, // If you need static images
    `gatsby-transformer-sharp`, // If you need dynamic images
  ],
}

StaticImage or GatsbyImage

The plugins we just installed include two different components that we can use to render images. One is called StaticImage , and one is GatsbyImage. StaticImage , as the name implies, is for static images, meaning that the images will always stay the same anytime this component will be rendered. For example, an image saved in your repository will always stay the same when rendered. Therefore, we would use the StaticImage component in this case. Note that the video of this section will only cover the StaticImage component. GatsbyImage , on the contrary, is used when the image changes. For example, when you reuse a same component but pass a different image every time, or when the image is coming from a content management system, GatsbyImage should be used.

Using StaticImage

First, add your image to your repository, or simply get a URL of an image hosted on the web. I have an image of a sleeping kitten, so I'll just add it to the src > images folder.

In IndexPage.js - or any component where you want to use StaticImage , and let's import StaticImage from gatsby-plugin-image.

// IndexPage.js

import { StaticImage } from "gatsby-plugin-image"

In the return body, we'll just call the StaticImage and pass the src and alt attributes, just like the img HTML tag. If you didn't add the image to your repo and want to take an image URL, instead of passing the local path to the src attribute, pass your URL.

// IndexPage.js

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" />

Using GatsbyImage

To display a dynamic image with GatsbyImage, we'll first need to query our image with GraphQL. A typical GraphQL query looks like this one below. Each image fetched with GraphQL will have the childImageSharp field, in which you can set the gatsbyImageData.

query {
 blogPost(id: { eq: $Id }) {
   title
   body
   image {
     childImageSharp {
       gatsbyImageData(width: 200)
     }
   }
 }
}

Between the parentheses of gatsbyImageData, you can pass properties to style your image. See the Styling the image section below to learn more about the different options offered. Once the styling is satisfactory, import GatsbyImage and the getImage from gatsby-plugin-image.

import { GatsbyImage, getImage } from "gatsby-plugin-image"

In your component, get the image from the graphQL query with the getImage function.

import { GatsbyImage, getImage } from "gatsby-plugin-image"

const MyComponent = ({ data }) => { // data is fetched from GraphQL and passed to this component
	const image = getImage(data.blogPost.image)

	return (<div>
		{/* Content of MyComponent... */}
	</div>)
}

export const MyComponent

Use the GatsbyImage component to display your image.

import { GatsbyImage, getImage } from "gatsby-plugin-image"

const MyComponent = ({ data }) => {
	const image = getImage(data.blogPost.image)

	return (<div>
		<GatsbyImage image={image} alt={data.blogPost.title}/>
	</div>)
}

export const MyComponent

Styling the image

Next it's time to add some styling and a placeholder to our image! Below, the first value provided (in camelCase) for each property is for the StaticImage component, and the value in parentheses (in SCREAMINGSNAKECASE) is for the GatsbyImage component. The example code provided below are all for StaticImage. For StaticImage , we pass the properties as JSX attributes.

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" layout="fixed" width={400} aspectRatio={3 / 4} formats={["auto", "jpeg"]} />

And for GatsbyImage , we pass it as arguments to the gatsbyImageData resolver.

query {
 blogPost(id: { eq: $Id }) {
   title
   body
   image {
     childImageSharp {
       gatsbyImageData(
         width: 200
         placeholder: BLURRED
         formats: [AUTO, WEBP, AVIF]
       )
     }
   }
 }
}

First, we have the layout property, which determines the size of the image and the resizing behaviour. Three options are available for this property.

• constrained (__CONSTRAINED __for GatsbyImage) - always keeps the aspect ratio of the original image. If the original image width is higher than the screen size, it'll scale down the image, with the same aspect ratio. This is the default value for layout.
• fixed (FIXED) - the size of the image will always stay the same. It'll either be the original size of the image or the size set with the width and height properties.
• fullWidth (FULL_WIDTH) - always displays the image at full width. Best used for banners and hero images. You can compare the three options by watching this short video.

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" layout="fixed" />

If the layout is set to constrained or fixed , we can adjust the width and height properties of our image. It accepts any number as value. If these values don't respect the original image's aspect ratio, the image will be cropped, and not stretched.

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" layout="fixed" width={400} height={400} />

The aspectRatio property can also be set. It accepts any fraction as a value, and the resulting image will be cropped. If you pass the aspectRatio property, only set a width or a height - and not both of them. gatsby-plugin-image will calculate the size depending on the aspect ratio provided.

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" layout="fixed" width={400} aspectRatio={3 / 4} />

Next up, we have our placeholder , which is what the user sees while the image is being loaded. Four options are available to you:

• dominantColor (DOMINANT_COLOR for GatsbyImage) - the dominant color of the image will fill the placeholder image as a solid background color. This is the default value for placeholder.
• blurred (BLURRED) - the user will see a blurred version of the image
• tracedSVG (TRACED_SVG)- a simple SVG version of the image will be generated, and works best with simple shapes
• none (NONE)- there's no placeholder while the image is being loaded We can also set the output formats of the generated image. It accepts an array of output formats. By default, it's set to ["auto", "webp"] (or [AUTO, WEBP] for GatsbyImage).

<StaticImage src="../images/sleeping-kitten.jpg" alt="Sleeping kitten" formats={["auto", "jpeg"]} />

Finally, we have some transformOptions to style our image even further. These are some advanced techniques, and most people don't need them. If you wish to transform your image, use the transformOptions property and set any option you wish that are in this list.