Configure the Image Field

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.

Screenshot of the Image field editor.

JSON model

The following table displays the JSON configuration options available in the JSON editor.


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, read more here!

Prismic's Image Optimization feature is possible thanks to our partnership with Imgix. This allows us to 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 right 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 JPEG.

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

Apply your own transformations

Because images are served through Imgix, you can add any other Imgix transformations that you like. Using string handling, remove, add, or modify the parameters in the URL.

const imageUrl = `,format&rect=255,0,1536,1536&w=500&h=500`
pixelizedImageUrl = imageUrl + `&px=10`

Refer to the Imgix documentation to learn more.

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, which can degrade the quality and increase the GIF's file size.

To ensure your GIFs optimization's success, use auto=format,compress for animated GIFs. It will actually 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? Get in touch with us on our Community Forum.