Image

Display responsive resource, custom, or CMS images

The Image component displays a project resource, custom URL, or CMS image. It supports separate light and dark images, responsive framing, lazy loading, fetch priority, an SVG mask, links, and an optional full-screen lightbox.

Supported Content and File Types

Use Image for bitmap resources such as JPG and PNG. Use the SVG component when the vector artwork itself needs fill or stroke styling.

How to Use Image

You’ll find Image under Media in the Components list.

Drag Image onto the page.
Choose Resource, Custom, or CMS.
Select or enter both Light and Dark sources if needed.
Add alternative text or complete the image metadata in Resources.
Configure file sizing, loading, aspect ratio, and optional lightbox or mask.

Component Settings

Image

Type

Resource — Uses an image stored in the project. This is the default.
Custom — Uses an absolute URL or site-relative path.
CMS — Uses a CMS field expression.

Mode switches between Light and Dark while choosing the source. Light is selected by default.

The dark image is shown automatically when the visitor’s browser or operating system is set to dark mode (prefers-color-scheme: dark). If no dark image is set, the light image is used everywhere.

Custom mode displays Source. CMS mode displays Field, which defaults to {{item.image.src}}. Both modes provide Alt text.

The Field value must be a Twig expression that outputs the image's URL, like the default {{item.image.src}}. Typing a front matter key on its own (for example image) won't work — wrap it as an expression, e.g. {{item.image}} if your front matter stores the URL directly.

CMS images show a placeholder while editing. Preview or publish the page to see the resolved CMS image.

For Custom and CMS sources, Width and Height define the intrinsic image size and default to 1280 × 720. Display size is controlled separately under Sizing.

For Resource images:

Original — Exports the original resource size. This is the default behaviour.
Custom — Exports a resized file. File Size defaults to 400 pixels.

Custom-sized resources are exported at twice the entered width for Retina displays. A File Size of 400 pixels creates an 800-pixel export.

Image Protection discourages simple right-click downloading and is off by default. It cannot prevent visitors from retrieving an image already delivered to their browser.

Lazy Loading adds the browser’s loading="lazy" attribute and is off by default. Avoid lazy loading a prominent image near the top of the page.

Fetch Priority offers Auto, High, or Low and defaults to Auto.

Optimised image dimensions and appropriate lazy loading can improve page performance without reducing visible quality.

Image Inspector controls for source, sizing, protection, lazy loading, and fetch priority

Mask

SVG selects the mask resource. Black or opaque areas reveal the image.

Size offers Contain, Cover, or Fill and defaults to Contain.

Enable opens the image full-screen when clicked and is off by default.

When enabled, Color defaults to Black, Opacity to 50%, and Blur to 0 pixels.

Image Lightbox controls for backdrop colour, opacity, and blur

Link

Set To to link the image. Avoid enabling both a Link and Lightbox because visitors need one clear click action.

Aspect Ratio

Aspect Ratio

Auto — Uses the image’s natural ratio. This is the default.
Wide — Uses 16:9.
Tall — Uses 4:5.
Custom — Uses an x/y value; the default is 7/5.

When the ratio is not Auto, Object Fit offers Fill, Contain, Cover, None, or Scale Down and defaults to Cover, and Position chooses the focal point from the centre, edges, or corners and defaults to Centre.

Image Aspect Ratio controls with object fit and position options

Image Inspector showing custom aspect-ratio settings

A Note About Image Protection

Browsers must download images before displaying them, so no front-end setting can make an image impossible to retrieve. Image Protection only discourages casual saving. Watermark valuable images and export them at an appropriate web resolution.

Accessibility

Describe informative images with concise alternative text. Leave alt text empty only for purely decorative images, and avoid repeating an adjacent caption word for word.