Image

This article explains how to implement Prismic's image field.


Prismic serves images from a powerful image hosting platform, enabling compression, formatting, and web optimization.

Here is what an image looks like from the Prismic API:

Copy
{
  "example_image": {
    "dimensions": {
      "width": 2048,
      "height": 1536
    },
    "alt": null,
    "copyright": null,
    "url": "https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format"
  },
  "mobile": {
    "dimensions": {
      "width": 500,
      "height": 500
    },
    "alt": null,
    "copyright": null,
    "url":" https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format&rect=255,0,1536,1536&w=500&h=500"
  }
}

Add an image to a content model

Before you can start using images in Prismic, you will need a project set up. To get started, choose your framework from the docs homepage.

Once you have a project, open the slice or type that you want to edit and add an image field.

You can define responsive views for your image. For each view, Prismic will serve a version of your image with the given dimensions. However, you can also customize image dimensions in your code using the SDKs that Prismic provides.

Edit images

The Page Builder provides functions for uploading, cropping, and managing images. To learn more, read Manage Images.

Render images

After you have fetched data from your repository, you need to render it in your UI code. The Prismic SDKs provide functions and components for rendering images:

React.js
React.js
Copy
import { PrismicImage } from '@prismicio/react'

<PrismicImage field={doc.data.myImageField} />
Next.js
Next.js
Copy
import { PrismicNextImage } from '@prismicio/next'

<PrismicNextImage field={doc.data.example_image} />
Nuxt 2
Nuxt 2
Copy
<prismic-image :field="document.data.example_image" />
Nuxt 3
Nuxt 3
Copy
<prismic-image :field="document.data.example_image" />
Vue.js
Vue.js
Copy
<PrismicImage :field="document.data.example_image" />
SvelteKit
SvelteKit
Copy
<script>
  import { PrismicImage } from "@prismicio/svelte"
</script>

<PrismicImage field={document.data.example_image} />
Express
Express
Copy
<% const image = prismic.asImageSrc(document.data.example_image) %>

<img 
  src="<%- image.src %>"
  alt="<%- document.data.example_image.alt %>"
/>
Vanilla JavaScript
Vanilla JavaScript
Copy
import * as prismic from '@prismicio/client'

const src = prismic.asImageSrc(document.data.example_image)

const image = `
  <img
    src="${src}"
    alt="${document.data.example_image.alt}"
  />
`

Prismic's image optimization feature is possible thanks to our partnership with Imgix. We dynamically compress and optimize your images, improving your website performance and SEO.

You can apply any Imgix transformation to your image. This example will make an image black and white:

Current technology
MISSING CODE SNIPPET FOR THIS TECHNOLOGY
React.js
React.js
Copy
import { PrismicImage } from '@prismicio/react'

<PrismicImage 
  field={doc.data.myImageField}
  imgixParams={{ sat: -100 }} 
/>
Next.js
Next.js
Copy
import { PrismicNextImage } from '@prismicio/next'

<PrismicNextImage 
  field={doc.data.example_image} 
  imgixParams={{ sat: -100 }} 
/>
Nuxt 2
Nuxt 2
Copy
<prismic-image 
  :field="document.data.example_image" 
  :imgix-params="{ sat: -100 }"
/>
Nuxt 3
Nuxt 3
Copy
<prismic-image 
  :field="document.data.example_image" 
  :imgix-params="{ sat: -100 }"
/>
Vue.js
Vue.js
Copy
<PrismicImage 
  :field="document.data.example_image"
  :imgix-params="{ sat: -100 }"
/>
SvelteKit
SvelteKit
Copy
<script>
  import { PrismicImage } from "@prismicio/svelte"
</script>

<PrismicImage 
  field={document.data.example_image} 
  imgixParams={{ sat: -100 }}
/>
Express
Express
Copy
<% const image = prismic.asImageSrc(document.data.example_image, { sat: -100 }) %>

<img 
  src="<%- image.src %>"
  alt="<%- document.data.example_image.alt %>"
/>
Vanilla JavaScript
Vanilla JavaScript
Copy
import * as prismic from '@prismicio/client'

const src = prismic.asImageSrc(document.data.example_image, {
  sat: -100,
})

const image = `
  <img
    src="${src}"
    alt="${document.data.example_image.alt}"
  />
`

All images distributed through the API have the Imgix URL parameter auto: "compress,format".

The format operation distributes each image in the proper format for the browser. Images are served in WebP format wherever possible. If WebP is not supported, images with transparency are served as PNG8. All others are served as JPEGs.

The compress operation reduces the file size while maintaining as much visual information as possible.

To disable formatting and compression, set auto: false in your imgixParams.

Refer to the Imgix documentation to learn more about image formatting options.

Don't compress GIFs before uploading

It's best not to compress your GIFs before serving them with Imgix. Since we optimize images, uploading a pre-compressed GIF can have the opposite effect, degrading the quality and increasing the GIF's file size.

Imgix's automatic compression will turn GIFs into an animated WebP in supported browsers (such as Chrome).


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.