Image component and parameters

You can render Sitecore image fields in your Content SDK Angular app with the scImage structural directive from @sitecore-content-sdk/angular. Use its imageParams input to add query string parameters to the image URL, for example, to request server-side resizing.

The directive applies the image field's src, alt, width, and height values to an HTML img element. If the field value includes a srcSet array, the directive also generates a srcset attribute. In editing mode, it includes field metadata markers and displays a placeholder for an empty image field when metadata is available.

Render an image field

Import ScImageDirective and add it to your component's imports array. Pass the image field to *scImage in the component template:

import { Component, input } from '@angular/core';
import { ScImageDirective, type ImageField } from '@sitecore-content-sdk/angular';

@Component({
  selector: 'app-content-image',
  imports: [ScImageDirective],
  template: `<img *scImage="imageField()" />`,
})
export class ContentImageComponent {
  readonly imageField = input<ImageField>();
}

Pass the complete field object, including its value and metadata properties, to preserve support for editing in SitecoreAI. The directive also accepts a raw image field value, but that value doesn't include field metadata.

Specify query parameters for the media URL

To request a resized image, specify image parameters through the directive's imageParams input. For example, the following template requests an image with a maximum width of 100 pixels and a maximum height of 50 pixels:

<img *scImage="imageField(); imageParams: { mw: 100, mh: 50 }" />

The directive adds mw and mh to the media URL as query string parameters. These parameters control the requested image rendition. The HTML width and height attributes come from the image field value, independently of imageParams.

Image parameters

The following table describes the Sitecore media parameters you can pass through imageParams:

Key	Description
`w`	Width in pixels.
`h`	Height in pixels.
`mw`	Maximum width in pixels.
`mh`	Maximum height in pixels.
`la`	Language. Defaults to the context language.
`vs`	Version. Defaults to the latest version.
`db`	Database name. Defaults to the context database.
`bc`	Background color. Defaults to black.
`as`	Whether the image can stretch or increase beyond its original size. Use `1` to enable stretching or `0` to disable it.
`iar`	Whether to ignore the aspect ratio when resizing. Use `1` to ignore the aspect ratio or `0` to preserve it.
`sc`	Scale factor. For example, `sc: 0.25` scales the image to 25% of its original size.
`thn`	Whether to return a thumbnail. Use `1` to return a thumbnail or `0` to return the regular image.
`dmc`	Whether to disable media caching for retrieval and storage. Use `1` to disable caching or `0` to enable it.

Note

Parameter support and defaults depend on the media service that serves the image. Experience Edge documents support for w, h, mw, mh, and the file format parameter f. For images served through Experience Edge, see Working with media.

Render a responsive image

To render a responsive image, provide a srcSet array in the image field value and add the standard HTML sizes attribute to the img element. For example, an image field value can include the following candidate sizes:

srcSet: [{ mw: 300 }, { mw: 100 }]

Use the following template with that field:

<img
  *scImage="imageField(); imageParams: { mw: 300 }"
  sizes="(min-width: 960px) 300px, 100px"
  class="img-fluid"
/>

The directive combines imageParams with each entry in the field value's srcSet array to generate the candidate URLs. Parameters in a srcSet entry override matching keys in imageParams. Each candidate must provide w or mw so the directive can generate its width descriptor.

The browser uses srcset and sizes to select an image candidate. Adding sizes or imageParams without a srcSet array doesn't generate responsive image candidates.

If you have suggestions for improving this article, let us know!