Image API examples

Gatsby offers rich integration with Contentful's Image API

Images can be display with three different layouts. Learn more about them in the reference of gatsby-plugin-image

• Constrained
• Fixed
• Full width

All placeholder variants are supported as well. See more at thereference of gatsby-plugin-image

• Blurred
• Traced SVG

Constrained

This is the default layout. It displays the image at the size of the source image, or you can set a maximum size by passing in width orheight). If the screen or container size is less than the width of the image, it scales down to fit, maintaining its aspect ratio. It generates smaller versions of the image so that a mobile browser doesn’t need to load the full-size image.

GraphQL query

{
  allContentfulAsset {
    edges {
      node {
        title
        gatsbyImageData(layout: CONSTRAINED, width: 186)
      }
    }
  }
}

Fixed

This is a fixed-size image. It will always display at the same size, and will not shrink to fit its container. This is either the size of the source image, or the size set by the width and height props. Only use this if you are certain that the container will never need to be narrower than the image.

GraphQL query

{
  allContentfulAsset {
    edges {
      node {
        title
        gatsbyImageData(layout: FIXED, width: 100, height: 100)
      }
    }
  }
}

Full width

Use this for images that are always displayed at the full width of the screen, such as banners or hero images. Like the constrained layout, this resizes to fit the container. However it is not restricted to a maximum size, so will grow to fill the container however large it is, maintaining its aspect ratio. It generates several smaller image sizes for different screen breakpoints, so that the browser only needs to load one large enough to fit the screen. You can pass a breakpoints prop if you want to specify the sizes to use, though in most cases you can allow it to use the default.