Configuring the JSS NextImage component

Version: 22.x

The JSS NextImage component is a field rendering helper component that you use to display images configured in Sitecore fields with a Next.js Image component.

The JSS NextImage component uses built-in image optimization provided by Vercel, but you can provide your own loader if required with the help of the loader property. In versions of JSS prior to 21.6.1, the NextImage component uses a custom loader.

The component uses the JSS Media API and the Headless Services media handler to resize images.

Note

To use the NextImage component, you must update @sitecore-jss/sitecore-jss-nextjs to version 20.1.0 or later.

The following table contains the properties you can use to configure the NextImage component:

Name	Type	Description
`field`	`ImageField \| ImageFieldValue`	Required. Image field data. The data is provided by a `Placeholder` component.
`editable`	`boolean`	Indicates whether the Sitecore-formatted output must be used. Default: `true`.
`mediaUrlPrefix`	`RegExp`	A regular expression that finds the media URL prefix to be replaced by `/-/jssmedia` or `/~/jssmedia`.
`imageParams`	`ImageSizeParameters[]`	The query string parameters to append to the image URL.

In addition to the properties listed in the previous table, the NextImage component supports all the properties of the Next.js Image component except src.

Note

If you add the src property, the component throws an error. To directly provide an image source URL through the src property, you must use the next/image component.

Examples

You can use the NextImage component to display editable or non-editable responsive images.

Simple image

The following example shows how to display a responsive, optimized, editable image:

RequestResponse

<NextImage field={props.fields.image} height="51" width="204" />

Advanced image with image size parameters

The following example shows how to display a non-editable image where you control the resizing and editing:

RequestResponse

<NextImage
  field={props.fields.image}
  editable={false}
  unoptimized={true}
  imageParams={{ mw: 100, mh: 50 }}
  height="50"
  width="94"/>

In this example:

editable - controls whether the image can be edited in Sitecore Experience Editor.
unoptimized - disables next/image source optimization in favor of imageParams.
imageParams - image sizing parameters that are passed to Sitecore to resize the image server-side.

Important

Because JSS does not support security hashing of media URLs, you must white-list these parameter sets on the server.

Do you have some feedback for us?

If you have suggestions for improving this article,