Image Field Reference

This article explains what the Image field is and how to configure it in the Custom Type builder.

The Image field allows content writers to upload an image with variable size constraints, which developers can use for responsive layouts.

Image field configuration

The following are the instructions to configure an Image field in a Custom Type.

Screenshot of the Image field in the drag-and-drop editor.

The visual builder

When configuring an Image field, you'll see the options to set the Field name and API ID. Then, in the "Responsive views" section, you can configure the size constraints.

To define a full-size version, leave the Width and Height fields empty; this will be automatically set up as auto x auto. If you adjust one field and leave the other one blank, the blank field will be auto.

Slice Machine vs. Legacy Editor

Editing fields is almost identical in Slice Machine and the Legacy editor. But it is important to know that the mock config option (to add data to preview content fields in the Slice Simulator) is only available in Slice Machine.

Screenshot of the Image field editor.

JSON model

The following table displays the JSON keys and values of the field’s 'API response.

Edit the JSON model with caution

Only edit the JSON model to make changes to the Rich Text field labels. Making abrupt changes can cause conflicts when synchronizing changes with your documents.


string (required)

Value must be Image



Object for the configuration options



Sets the label that shows up for the field in the entry editor



A user-friendly placeholder for the field in the entry editor



The width and height constraints for the image.



An integer will define the width of the image in pixels. If you set as null, there will be no constraint.



An integer will define the height of the image in pixels. If you set as null, there will be no constraint.



Define the responsive image views for the image. For each view, give an object with a name, width, and height.


The name for the image view



An integer that defines the width of the image view in pixels



An integer that defines the height of the image view in pixels

Example JSON configuration

The following JSON defines an Image field that has size constraints and a mobile view:

"example_image": { 
  "type": "Image", 
  "config": { 
    "constraint": { 
      "width": 600, 
      "height": 1200 
    "thumbnails": [ 
        "name": "mobile", 
        "width": 200, 
        "height": 300 
     "label": "featured image", 
     "placeholder": "Upload an image..." 

API response example

Below you can see an example API response of an Image field with the API ID of example_image that has a mobile responsive view:

// API response example of an Image field

  // ...

Image optimization

Attention: We've changed the way we handle SVG's, learn more!

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.

What are the transformations that we are doing automatically?

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.

Apply your transformations

Prismic's package for templating with JavaScript includes helper methods for formatting Prismic images. Because the images are served through Imgix, you can add any Imgix transformations that you like — or disable the default compression and formatting.

import * as prismicH from "@prismicio/helpers"

const src = prismicH.asImageSrc(, {
  sat: -100,

const image = `

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

Warning about GIFs

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.

To ensure your GIFs optimization's success, use auto=format,compress for animated GIFs. It will turn those 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.