Image
The Image component provides a reusable pattern for image in the interface.
Plain image
Just a plain image
Rounded corners
An image with border radius for rounded corners
Missing plain image
Image not found but rendered as a placeholder.
Full width image
Image in full width mode.
Cover image
Image with cover mode, that covers the parent container.
Container query switching (default)
The default behaviour for an ImageInterface source with several candidate sizes: one <img> per size, switched by CSS container queries. Inspect the element to see multiple <img> tags, only one of which is visible at a time.
Single image via srcset (opt-in)
Setting preferSrcset renders a single <img> using srcset, sizes and container query data instead of one <img> per breakpoint. Inspect the element to verify only one <img> is rendered.
Focus point
A responsive image with an off-center focus point, verifying that object-position is applied together with the srcset/sizes attributes.
Low quality image placeholder
A responsive image with a low quality placeholder shown as a background while the full image loads.
Single candidate size
An image contract with only one candidate size. No srcset or sizes attribute should be rendered.
Eager loading with priority
Overriding imgAttributeList to opt out of the lazy-loading default, useful for above-the-fold images such as a Hero background.
API
| Parameter | Default | Description |
|---|---|---|
|
src
|
false | A string containing a valid URL or an ImageInterface object. If the object is used, the srcset attribute is ignored. |
|
srcset
|
false | A string containing a valid srcset attribute. Ignored if src is an ImageInterface object. |
|
alt
|
Alt text of the imag. May override the alt text of the ImageInterface object. | |
|
caption
|
Image caption. That will be visible for the user. | |
|
removeCaption
|
false | Removes the visible caption. The caption may still be used as an alt-text for the image. |
|
byline
|
Byline for additional information, placed under the caption | |
|
fullWidth
|
false | If the image should obtain the --full-width modifier. |
|
cover
|
false | If the image should obtain the --cover modifier. |
|
rounded
|
false | Border radius of the image, false for no radius. Accepted values are xs, sm, md, lg, full (circle) |
|
placeholderEnabled
|
true | If the placeholder should be enabled, if false, the component will not render at all if the src is empty |
|
placeholderText
|
false | Label to show if image is missing |
|
placeholderIcon
|
broken_image | Icon to display if image is missing / false to hide |
|
placeholderIconSize
|
xxl | Icons size, please refer to image component for size. |
|
imgAttributeList
|
[] | Attributes for the img element. |
|
lqipEnabled
|
true | If the low quality image placeholder should be enabled. |
|
calculateAspectRatio
|
true | If the aspect ratio should be calculated based on the image dimensions. This option will be ignored if cover is set to true. |
CSS API
| Variable | Default | Type | Values | Description |
|---|---|---|---|---|
|
--c-image--space
|
var(--space) | range | - | Base spacing unit. Used for padding and margin inside components. |
|
--c-image--color--background-alt
|
var(--color--background-alt) | color | - | Manual companion token for subtle background surfaces. |
|
--c-image--color--background-contrast-muted
|
var(--color--background-contrast-muted) | color | - | Derived muted contrast for text and icons on background surfaces. |
|
--c-image--border-width
|
var(--border-width) | range | - | Border width |
|
--c-image--color--surface-border
|
var(--color--surface-border) | color | - | Manual companion token for borders on surface elements. |
|
--c-image--color--surface-contrast
|
var(--color--surface-contrast) | color | - | Used for text and icons on surface backgrounds with less contrast. |
|
--c-image--corner-shape
|
var(--corner-shape) | select | square, round, squircle, circular, bevel, scoop | Corner shape |
|
--c-image--font-size-90
|
var(--font-size-90) | range | - | One step below base in the type scale. |
|
--c-image--font-family-heading
|
var(--font-family-heading) | font | - | Falls back to body font if not set. |
|
--c-image--font-weight-bold
|
var(--font-weight-bold) | select | 100, 200, 300, 400, 500, 600, 700, 800, 900 | Placeholder font weight |
|
--c-image--line-height-base
|
var(--line-height-base) | range | - | Caption line height |
|
--c-image--border-radius-multiplier
|
1 | range | - | Scales the border radius locally without changing the global border radius scale. |