Rendering the Image field

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

The Image field allows content writers to upload an image that can be configured with size constraints and responsive image views. Thanks to Prismic's Imgix integration, these images will be delivered already optimized.

You can see our documentation for retrieving the image field here.

NOTE: The examples on this page assume that you have retrieved your content and stored it in a variable named document.

Render the image url & alt text

The easiest way to render an image is to retrieve and add the image url and alt text to image elements. Here is an example that renders the url and alt text from an Image field with the API ID of illustration.

Copy
<img src={document.illustration.url} alt={document.illustration.alt} />

Get an image view

It's easy to get the url for an image and any of its views. The following shows how to retrieve the image url for the main view as well as its tablet and mobile views using the picture tag. In this case, the Image field has an API ID of responsive_image.

Copy
const mainView = document.responsive_image
const tabletView = document.responsive_image.tablet
const mobileView = document.responsive_image.mobile
return (
  <picture>
    <source media="(max-width: 400px)" srcSet={mobileView.url} />
    <source media="(max-width: 900px)" srcSet={tabletView.url} />
    <source srcSet={mainView.url} /> 
    <img src={mainView.url} alt={mainView.alt} />
  </picture>
)

If you added an alt text or copyright text value to your image, you retrieve them as shown below. The Image field in the example below has the API ID of image_with_copyright.

Copy
const image = document.image_with_copyright
const imageCopyright = image.copyright
const imageAlt = image.alt

The following example shows how to retrieve the alt & copyright text for a responsive image view. Note that the alt and copyright text will be the same for all views.

Copy
const mobileView = document.image_with_copyright.mobile
const mobileUrl = mobileView.url
const mobileCopyright = mobileView.copyright
const mobileAlt = mobileView.alt

Get the image Width & Height

Here's how to retrieve the main image's width or height. Here, the Image field has the API ID of featured_image.

Copy
const featuredImage = document.featured_image
const imageWidth = featuredImage.dimensions.width
const imageHeight = featuredImage.dimensions.height

Here is how to retrieve the width and height for a responsive image view.

Copy
const mobileImage = document.featured_image.mobile
const mobileWidth = mobileImage.dimensions.width
const mobileHeight = mobileImage.dimensions.height

Full example

Now let's take a look at a simple full page component example. In this example we dynamically query a document by UID, then render the Image field on the page by using the HTML img tag and passing the url in to the src attribute. Then we pass the alt tag in to the alt attribute. The API ID of the image here is image_field.

Copy
import React from 'react'
import { graphql } from 'gatsby'

const Post = ({ data }) => {
  const document = data.prismic.allPosts.edges[0].node
  if (!document) return null
  return (
    <img src={document.image_field.url} alt={document.image_field.alt} />
  )
}

// Query for the Blog Post content in Prismic
export const query = graphql`
query BlogPostQuery($uid: String) {
  prismic {
    allPosts(uid: $uid){
      edges {
        node {
          _meta {
            uid
          }
          image_field
        }
      }
    }
  }
}
`

export default Post