Docs Developer Site
Developer Docs CMS reference docs next Richtext Image component

Image component

Contents

Advanced component for inserting and managing images in rich text.

Introduction

The HtmlArea’s built-in image function embeds a managed image in rich text. Unlike a plain <img>, it references an image content item by ID, may include a caption, and can apply a custom image style — cropping and filters are handled server-side, and the URL is resolved at render time.

Appearance

In Content Studio, the HtmlArea editor provides a standard image dialog that allows editors to insert images and control the basic styling.

Image dialog with all available options where the style dropdown is opened
Figure 1. The image dialog is available from the editor toolbar

Raw format

The inserted image is stored as a <figure> element wrapping an <img> that references the image by ID, optionally with a <figcaption> caption and a style class:

<figure class="editor-style editor-image-cinema">
  <img alt="Mountain at dawn" src="image://a1b2c3d4-e5f6-7890-abcd-ef1234567890?style=editor-image-cinema"/>
  <figcaption>Sunrise over the summit</figcaption>
</figure>

  • image://<id> references an image content item — not a file URL — and must be resolved before rendering.

  • The optional <figcaption> holds the caption.

  • The style parameter selects the image style for server-side cropping and filters. The corresponding class supports editor and front-end styling.

Processed Format

Guillotine tags each image with data-image-ref in processedHtml. The structured images field provides the matching ref, image content, applied style, and URL components for src and srcset. The HTML attributes contain placeholders that the front-end must rewrite.

The processHtml argument on the HtmlArea field controls the image sizes: imageSrcWidth sets the main image width and imageWidths requests responsive variants. Styles come from applications configured on the project, or on the site selected by scopeKey.

{
  guillotine(project: "myproject", branch: "master") {
    get(key: "/articles/hello") {
      ... on com_example_myapp_Article {
        data {
          body(processHtml: {imageSrcWidth: 992, imageWidths: [600, 992]}) {
            processedHtml
            images {
              ref  (1)
              image {
                _id
                displayName
              }
              src { path queryString }
              srcset {
                width
                imageUrl { path queryString }
              }
              style {
                application
                name
                aspectRatio
                filter
              }
            }
          }
        }
      }
    }
  }
}
1 Matches the data-image-ref attribute in processedHtml, so a front-end can map each image tag to its data.
One entry in data.guillotine.get.data.body.images (IDs and fingerprints abbreviated) 
{
  "ref": "image-ref",
  "image": {
    "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "displayName": "Mountain at dawn"
  },
  "src": {
    "path": "/media:image/myproject/content-id:fingerprint/block-992-425/photo.jpg",
    "queryString": ""
  },
  "srcset": [
    {
      "width": 600,
      "imageUrl": {
        "path": "/media:image/myproject/content-id:fingerprint/block-600-257/photo.jpg",
        "queryString": ""
      }
    },
    {
      "width": 992,
      "imageUrl": {
        "path": "/media:image/myproject/content-id:fingerprint/block-992-425/photo.jpg",
        "queryString": ""
      }
    }
  ],
  "style": {
    "application": "com.example.myapp",
    "name": "editor-image-cinema",
    "aspectRatio": "21:9",
    "filter": null
  }
}

This example assumes the configured application defines the editor-image-cinema image style with a 21:9 aspect ratio. The corresponding image element in processedHtml carries data-image-ref="image-ref". The <figure>, caption and style class are retained.

Rendering

Match each data-image-ref to its entry in images. Build src by concatenating your public API or media base URL, src.path and src.queryString. Build each srcset entry from its imageUrl in the same way, followed by its width descriptor, such as 600w.

Use the returned paths and query strings unchanged: styles and transformations affect the generated URLs and fingerprints. Request every size through processHtml rather than editing a path. An unresolved image has src: null and an empty srcset; handle that case in the renderer.

See Guillotine rich-text images for complete field definitions and rendering examples, and Front-end integration for framework integrations.

Contents

Contents