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

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)

"/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)

"/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:

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”){

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.

👉 That was the 3-part series about gatsby-image. I hope it was helpful!




A mix of Frontend Development, Machine Learning, Musings about Creative AI and more

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Easily add CSS Blend Modes in Webflow using Combo Classes with just a click

Google Summer of Code With LibreOffice — Project Overview

What’s the difference between cloud backup and cloud sync?

Know-it-alls and Impostors: Software Development in a Nutshell

15 Top Food Delivery App Development Companies in 2020–21: Latest Survey

A 2020-Themed Advent Calendar

Making A Folder Of Images For Your GitHub Readme

Announcing the Witnet Grant Program

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alexa Steinbrück

Alexa Steinbrück

A mix of Frontend Development, Machine Learning, Musings about Creative AI and more

More from Medium

How to handle redirects with Netlify and React/Gatsby projects

HeadlessUI Dialogue Part 1 -Showing and hiding your dialog

The Essential Meta Tags for Social Media in examples

10 reasons why I love Material-UI