Image
This article explains what the image field is and how to configure it.
Content writers can upload, crop, and manage images through the Page Builder.
Prismic serves images through imgix, a powerful image hosting platform, enabling compression, formatting, and web optimization.
To learn more about image management capabilities, read Manage Images.
Add an image to a content model
Open Slice Machine
In your Prismic project, start Slice Machine to begin editing content models.
npx start-slicemachine --open
Add an image field
In Slice Machine, navigate to the slice, page type, or custom type you want to modify. Add an image field.
The label determines the label shown to content writers in the Page Builder. Use an easily understood name.
The API ID determines the property name in the Document API. Use a short, snake-cased name.
(Optional) Add responsive sizes
Images can be configured with multiple responsive sizes. Content writers can upload differently sized images with predetermined dimensions.
Open the field settings and add as many responsive sizes as desired.
Display images
Prismic provides image components for Next.js, Nuxt, and SvelteKit.
<PrismicNextImage field={slice.primary.my_image_field} />
See the <PrismicNextImage>
documentation to learn more.
Tips
Transform images through the API
You can apply any imgix transformation to your image using the
imgixParams
prop. All Prismic image components support theimgixParams
prop.This example makes an image black and white:
<PrismicNextImage field={slice.primary.my_image_field} imgixParams={{ sat: -100 }} />
Refer to the imgix documentation to learn more about image formatting options.
Images are automatically compressed
All images distributed through the API have an
auto=compress,format
URL parameter. The parameter automatically compresses the image and serves the most efficient format (usually WebP).To disable formatting and compression, set
auto: null
in yourimgixParams
.<PrismicNextImage field={slice.primary.my_image_field} imgixParams={{ auto: null }} />
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).
Use
isFilled.image()
to check if an image field has a valueimport { isFilled } from "@prismicio/client"; if (isFilled.image(slice.primary.my_image_field)) { // Do something if `my_image_field` has a value. }
API response
Here is what an image looks like from the Document API:
{
"example_image": {
"id": "uYM_PQJ8VvY",
"url": "https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format",
"alt": "An illustration of a roller skater.",
"copyright": null,
"dimensions": {
"width": 2048,
"height": 1536
}
}
}
When an image supports responsive sizes, each size is added as a property:
{
"example_image": {
// ...
"id": "uYM_PQJ8VvY",
"Mobile": {
"id": "uYM_PQJ8VvY",
"url": "https://images.prismic.io/slicemachine-blank/dcea6535-f43b-49a7-8623-bf281aaf1cb2_roller-skating.png?auto=compress,format&w=400&h=300",
"alt": "An illustration of a roller skater.",
"copyright": null,
"dimensions": {
"width": 400,
"height": 300
},
"edit": {
"x": 0,
"y": 0,
"zoom": 1,
"background": "transparent"
}
}
}
}