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.
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.
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.
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.
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, 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.
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.
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, 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?
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.