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.
The following are the instructions to configure an Image field in a Custom Type.
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.
type
string (required)
Value must be Image
config
object
Object for the configuration options
config.label
string
Sets the label that shows up for the field in the entry editor
config.placeholder
string
A user-friendly placeholder for the field in the entry editor
config.constraint
object
The width and height constraints for the image.
config.constraint.width
integer
An integer will define the width of the image in pixels. If you set as null, there will be no constraint.
config.constraint.height
integer
An integer will define the height of the image in pixels. If you set as null, there will be no constraint.
config.thumbnails
array
Define the responsive image views for the image. For each view, give an object with a name, width, and height.
config.thumbnails.name
string
The name for the image view
config.thumbnails.width
integer
An integer that defines the width of the image view in pixels
config.thumbnails.height
integer
An integer that defines the height of the image view in pixels
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..."
}
}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
{
// ...
"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"
}
}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.
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.
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(prismicDoc.data.example_image, {
sat: -100,
})
const image = `
<img
src="${src}"
alt="${prismicDoc.data.example_image.alt}"
/>
`Refer to the Imgix documentation to learn more about image formatting options.
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?
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.