Fields

Image

This article explains what the image field is and how to configure it.

A screenshot of an image field in the Page Builder.

An image field in the Page Builder.

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.

Prismic provides components for Next.js, Nuxt, and SvelteKit to display images.

import { PrismicNextImage } from "@prismicio/next";

<PrismicNextImage field={slice.primary.my_image_field} />;

Learn how content writers 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 Content 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.

import { PrismicNextImage } from "@prismicio/next";

<PrismicNextImage field={slice.primary.my_image_field} />;

See the <PrismicNextImage> documentation to learn more.

Transform images through the API

You can apply any imgix transformation to your image using the imgixParams prop. All Prismic image components support the imgixParams prop.

This example makes an image black and white:

import { PrismicNextImage } from "@prismicio/next";

<PrismicNextImage
  field={slice.primary.my_image_field}
  imgixParams={{ sat: -100 }}
/>;

See all of the available imgix parameters

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 AVIF).

It’s best not to compress your images before serving them with imgix. Since we optimize images, uploading a pre-compressed image can have the opposite effect, degrading the quality and increasing the image’s file size.

imgix’s automatic compression will turn GIFs into an animated WebP in supported browsers (such as Chrome).

To disable formatting and compression, set auto: null in your imgixParams.

import { PrismicNextImage } from "@prismicio/next";

<PrismicNextImage
  field={slice.primary.my_image_field}
  imgixParams={{ auto: null }}
/>;

Check if an image field has a value

Use isFilled.image() from @prismicio/client to check if an image field has a value.

import { isFilled } from "@prismicio/client";

if (isFilled.image(slice.primary.my_image_field)) {
  // Do something if `my_image_field` has a value.
}

Learn more about isFilled

API response

Here is what an image looks like from the Content 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"
      }
    }
  }
}
Was this page helpful?