Content Fragment Model

Ensure the Content Fragment field containing the image reference is of the content reference data type.

Field types are reviewed in the Content Fragment Model, by selecting the field, and inspecting the Properties tab on the right.

Content Fragment Model with content reference to an image

GraphQL persisted query

In the GraphQL query, return the field as the ImageRef type, and request the _dynamicUrl field. For example, querying an adventure in the WKND Site project and including image URL for the image asset references in its primaryImage field, can be done with a new persisted query wknd-shared/adventure-image-by-path defined as:

query($path: String!, $imageFormat: AssetTransformFormat=JPG, $imageSeoName: String, $imageWidth: Int, $imageQuality: Int) {
  adventureByPath(
    _path: $path
    _assetTransform: {
      format: $imageFormat
      width: $imageWidth
      quality: $imageQuality
      preferWebp: true
    }
  ) {
    item {
      _path
      title
      primaryImage {
        ... on ImageRef {
          _dynamicUrl
        }
      }
    }
  }
}

Query variables

{
  "path": "/content/dam/wknd-shared/en/adventures/bali-surf-camp/bali-surf-camp",
  "imageFormat": "JPG",
  "imageWidth": 1000,
}

The $path variable used in the _path filter requires the full path to the content fragment (for example /content/dam/wknd-shared/en/adventures/bali-surf-camp/bali-surf-camp).

The _assetTransform defines how the _dynamicUrl is constructed to optimize the served image rendition. Web-optimized images URLs can also be adjusted on the client by changing the URL’s query parameters.

GraphQL parameterDescriptionRequiredGraphQL variable values
formatThe format of the image asset.GIF, PNG, PNG8, JPG, PJPG, BJPG, WEBP, WEBPLL, WEBPLY
seoNameName of file segment in URL. If not provided the image asset name is used.Alphanumeric, -, or _
cropCrop frame taken out of the image, must be within the size of the imagePositive integers defining a crop region within the bounds of the original image dimensions
sizeSize of the output image (both height and width) in pixels.Positive integers
rotationRotation of the image in degrees.R90, R180, R270
flipFlip the image.HORIZONTAL, VERTICAL, HORIZONTAL_AND_VERTICAL
qualityImage quality in percent of original quality.1-100
widthWidth of the output image in pixels. When size is provided width is ignored.Positive integer
preferWebPIf true and AEM serves a WebP if the browser supports it, regardless of the format.true, false

GraphQL response

The resulting JSON response contains the requested fields containing the web-optimized URL to the image assets.

{
  "data": {
    "adventureByPath": {
      "item": {
        "_path": "/content/dam/wknd-shared/en/adventures/bali-surf-camp/bali-surf-camp",
        "title": "Bali Surf Camp",
        "primaryImage": {
          "_dynamicUrl": "/adobe/dynamicmedia/deliver/dm-aid--a38886f7-4537-4791-aa20-3f6ef0ac3fcd/adobestock_175749320.jpg?preferwebp=true&width=1000&quality=80"
        }
      }
    }
  }
}

To load the web-optimized image of the referenced image in your application, used the _dynamicUrl of the primaryImage as the image’s source URL.

In React, displaying a web-optimized image from AEM Publish looks like:

// The AEM host is usually read from a environment variable of the SPA.
const AEM_HOST = "https://publish-p123-e456.adobeaemcloud.com";
...
let dynamicUrl = AEM_HOST + data.adventureByPath.item.primaryImage._dynamicUrl;
...
<img src={dynamicUrl} alt={data.adventureByPath.item.title}/>

Remember, _dynamicUrl does not include the AEM domain, so you must provide the desired origin for the image URL to resolve.

Responsive URLs

The above example shows using a single size image, however in web experiences, responsive image sets are often required. Responsive images can be implemented using img srcsets or picture elements. The following code snippet shows how to use the _dynamicUrl as a base. width is a URL parameter that you can then append to _dynamicUrl for powering different responsive views.

// The AEM host is usually read from a environment variable of the SPA.
const AEM_HOST = "https://publish-p123-e456.adobeaemcloud.com";
...
// Read the data from GraphQL response
let dynamicUrl = AEM_HOST + data.adventureByPath.item.primaryImage._dynamicUrl;
let alt = data.adventureByPath.item.title;
...
{/*-- Example img srcset --*/}
document.body.innerHTML=`<img>
    alt="${alt}"
    src="${dynamicUrl}&width=1000}"
    srcset="`
      ${dynamicUrl}&width=1000 1000w,
      ${dynamicUrl}&width=1600 1600w,
      ${dynamicUrl}&width=2000 2000w,
      `"
    sizes="calc(100vw - 10rem)"/>`;
...
{/*-- Example picture --*/}
document.body.innerHTML=`<picture>
      <source srcset="${dynamicUrl}&width=2600" media="(min-width: 2001px)"/>
      <source srcset="${dynamicUrl}&width=2000" media="(min-width: 1000px)"/>
      <img src="${dynamicUrl}&width=400" alt="${alt}"/>
    </picture>`;