Template Images

Here you'll learn how to template your images when using Gatsby and Prismic.

🕙 Before reading

This page assumes that you have saved the response of your queries in a variable named document and that you've already installed the prismic-reactjs library. You'll use this library to import helper components into your templates, as shown below:

import { Link, RichText } from 'prismic-reactjs'

Image fields

Image fields can have alt text, copyright, and alternate responsive views, which can also have their own alt text. Here's a truncated example response of an Image field with one mobile responsive view:

Copy

{
  "example_image": {
    "alt": "Main image",
    "copyright": "author property",
    "thumbnails": {
      "mobile": {
        "dimensions": {
          "height": 50,
          "width": 50
        },
        "alt": "Mobile image",
        "copyright": "author property",
        "url": "https://images.prismic.io/slicemachine-blank/dcea6d535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?ixlib=gatsbyFP&auto=compress%2Cformat&fit=max&q=50&rect=246%2C0%2C1536%2C1536&w=50&h=50"
      }
    },
    "url": "https://images.prismic.io/getting-started-tutorial/f1a79126-1f80e-4db2-863d-7d891c81044b_home-banner.jpg?ixlib=gatsbyFP&auto=compress%2Cformat&fit=max&q=50&rect=0%2C0%2C4896%2C3263&w=2000&h=1333"
  }
}

Image thumbnails

If an Image field is configured with multiple sizes, its individual images can be queried using the thumbnails field. Each thumbnail within the field can be queried just like its primary image.

A query for a thumbnail named mobile could look like the following:

Copy

query Home {
  prismicHomepage {
    data {
      example_image {
        thumbnails {
          Mobile {
            url
            alt
          }
        }
      }
    }
  }
}

You can template images using an img tag, or a picture tag if you have multiple responsive thumbnail views:

<img/>
<picture/>

Copy

<img src={document.data.example_image.url} alt={document.data.example_image.alt} />

Copy

<picture>
   <source
     srcSet={document.data.example_image.thumbnails.mobile.url : ''}
     alt={document.data.example_image.thumbnails.mobile.alt : ''}
     media="(max-width: 500px)"
   />
   <source
     srcSet={document.data.example_image.thumbnails.tablet.url : ''}
     alt={document.data.example_image.thumbnails.tablet.alt : ''}
     media="(max-width: 1100px)"
   />
   <img
     src={document.data.example_image.url : ''}
     alt={document.data.example_image.alt : ''}
   />
</picture>

Image processing

Images from Prismic can be automatically optimized and scaled using Gatsby's image plugin, gatsby-plugin-image.

You can process image data for gatsby-plugin-image using one of the following methods:

Recommended: On-the-fly transformed using Imgix: Images are not downloaded to your computer or server and instead are transformed using Prismic's Imgix integration to resize images on the fly.
Locally transformed at build-time: Images are downloaded to your computer or server, resizing images at build-time.

You can apply image processing to any Image field and its thumbnails on a document. Image processing of inline images added to Rich Text fields is currently not supported.

Imgix transformed images

Using this method, images are manipulated on Imgix's servers at request time, eliminating the need to download and resize images on your computer or server. This results in quicker build times.

You can query image data for gatsby-plugin-image's GatsbyImage component like the following example.

Copy

query Home {
  prismicHomepage {
    data {
      example_image {
        gatsbyImageData
      }
    }
  }
}

Arguments can be passed to the gatsbyImageData field to change its presentation. See Gatsby's official documentation on the Gatsby Image plugin to learn more about the available arguments.

Locally transformed images

Using this method, images are downloaded to your computer or server and resized locally. Images are served from the same host as the rest of your app. This incurs additional build time as image processing is time-consuming.

To use local image processing, you need the following plugins in your project's gatsby-config.js:

You can query image data for gatsby-plugin-image's GatsbyImage component like the following example.

Copy

query Pages {
  allPrismicPage {
    nodes {
      data {
        imageFieldName {
          localFile {
            childImageSharp {
              gatsbyImageData
            }
          }
        }
      }
    }
  }
}

Arguments can be passed to the gatsbyImageData field to change its presentation. See Gatsby's official documentation on the Gatsby Image plugin to learn more about the available arguments.

gatsby-image support

Gatsby's previously recommended image component, gatsby-image, is now replaced by gatsby-plugin-image. Although Prismic's Gatsby plugin supports gatsby-image, it has been deprecated by Gatsby. We recommend all users migrate to gatsby-image-image instead.

If you need to continue using gatsby-image, you can query image data similarly to the gatsby-plugin-image queries listed above.

Imgix transformed images

Rather than querying for gatsbyImageData like shown above, you may query for fixed or fluid depending on the presentation of your image.

Use this pattern, where ...ImageFragment is one of the following fragments:

GatsbyImgixFixed
GatsbyImgixFixed_noBase64
GatsbyImgixFluid
GatsbyImgixFluid_noBase64

Copy

query Home {
  prismicHomepage {
    data {
      example_image {
        fluid {
           ...ImageFragment
        }
      }
    }
  }
}

Locally transformed images

Rather than querying for gatsbyImageData like shown above, you may query for fixed or fluid depending on the presentation of your image.

Use this pattern, where ...ImageFragment is one of the gatsby-transformer-sharp fragments.

Copy

query Pages {
  allPrismicPage {
    nodes {
      data {
        imageFieldName {
          localFile {
            childImageSharp {
              ...ImageFragment
            }
          }
        }
      }
    }
  }
}

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.