Understanding gatsby-image (Part 3): Controlling sizes, breakpoints and styling

3 min readDec 7, 2019

This is Part 3 of a three-part series covering the Gatsby plugin gatsby-image
Part 1: Graphql, generated files & markup
Part 2: Responsive images 101
Part 3: Controlling src-set, breakpoints and styling

Gatsby Image: What src-set property does it generate?

If you’re dealing with a fixed image it is producing a src-set with a width-descriptor appended to each source (e.g. 600w)

"srcSet": 
 "/static/1234/1111/my-image.jpg 600w, 
  /static/1234/2222/my-image.jpg 900w”

In the case of a fluid image it is producing a src-set with an x-descriptor appended to each source (e.g. 1.5x)

"srcSet": 
 "/static/1234/1111/my-image.jpg 1x, 
  /static/1234/2222/my-image.jpg 1.5x, 
  /static/1234/3333/my-image.jpg 2x”

Gatsby Image: What sizes property does it generate?

This only applies to fluid images. Fixed images don’t have a size property, because they use x-descriptors in their srcSet property.

Gatsby image just takes the sizes property from what gatsby-plugin-sharp is outputting. Remember, in Part 1 we showed how the fragment “GatsbyImageSharpFluid” includes a “size” property.

If you haven’t indicated a maxWidth in your graphql query it will generate:

sizes="(max-width: 800px) 100vw, 800px"

If you have indicated a maxWidth of 1200px, it will look like this:

sizes="(max-width: 1200px) 100vw, 1200px"

You can see here that the 100vw is based on the assumption that your image will take up the full available viewport width. It doesn’t take into account that your full-width image might be smaller because it’s living in a container with paddings and margins. So what can you do?

Setting custom sizes and breakpoints

You can adjust that to your needs, by overriding the sizes property in the object you pass to the fluid property of your gatsby image. In case your image lives in a container that has a margin of 20px on each side, you can substract 40px from the viewport width:

<Img
  fluid={{
    ...img.image,
    sizes: "(max-width: 1200px) calc(100vw - 40px), 1200px",
  }}
/>

This way you don’t load images that are much bigger than what you really need. You might also want to override the sizes property to add additional breakpoints:

sizes: "(max-width: 300px) calc(100vw - 20px), (max-width: 600px) calc(100vw - 40px), 1200px",

Another technique for overriding sizes is to include your custom sizes as a query parameter in your graphql query, like in this example:

childImageSharp { 
  fluid(sizes: “(max-width: 1200px) calc(100vw - 40px), 1200px”){ 
   ...GatsbyImageSharpFluid
  } 
}

Controlling which image sizes are generated

If you want more control over which image sizes are generated by gatsby-plugin-sharp you can use the srcSetBreakpoints parameter in your fluid query. This could be an array like [200, 350, 900]. You probably want to use this in combination with a custom sizes property in the gatsby-image React component, like described above. This way you can refer to concrete numbers in your sizes property.

Checkout the documentation of gatsby-plugin-sharp here: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp#parameters-2

Ways to style/layout the image created by gatsby-image

We’ve covered the markup and layout that gatsby-image creates in the first Part 1 of this series.

The <Image/> component from gatsby-image accepts the following properties related to styling:

style={} /* styles for the wrapper container */
imgStyle={} /* Styles for the actual img element */

Here’s an interesting discussion of how to apply custom styling to a gatsby image.