CMS Responsive Images ​

Images placed in CMS pages, CMS blocks and widget content are normally inserted by the WYSIWYG editor as a plain <img> pointing at the uploaded file, so every visitor downloads the full-size upload. The directive and the widget below render that same upload through the Image Resizer instead: one source per breakpoint, WebP (and AVIF when enabled), retina candidates, and a reserved box so the page does not shift while the image loads.

There are two ways to place one. Both produce the same markup, so the choice is only about where the content is edited.

The WYSIWYG directive ​

Insert the directive anywhere in CMS page or block content:

{{responsive_image src="wysiwyg/home/hero.jpg" role="hero" alt="Spring collection" eager="1"}}

A source that is empty, external or a data: URI renders nothing, a missing file falls back to the resizer placeholder, and a render error is logged and produces no output. One broken directive cannot take the page down.

The widget ​

The same renderer is available as a widget under Content > Widgets > Add Widget, widget type Venta - Responsive Image.

The widget can also be inserted into content through the WYSIWYG Insert Widget button, which writes a directive.

Roles and sizes ​

A role is a named slot size, declared in the theme's etc/view.xml under the Magebit_VentaTheme block. Each role has a _mobile sibling, and the renderer emits a mobile source up to 767px wide plus a desktop source above it.

The heights above are nominal. The roles are rendered with matchSourceAspectRatio(true) and no frame, so the width is honoured and the height is recomputed from the upload's own proportions. An image is never cropped or padded to fit its role.

Pick the role that matches the slot the image sits in, not the size of the file you uploaded. A hero image in a narrow column downloads far more pixels than the slot can show.

To change a size for a project, override the matching cms_image_* entry in the child theme's view.xml. A project that ships its own view.xml and does not carry these entries gets unresized images, since the role cannot be resolved.

Above the fold ​

By default the image loads lazily behind a blurred placeholder that fades out once the file arrives, which is the right behaviour for anything below the first screen.

Setting eager="1" (or Above the Fold: Yes) loads the image eagerly with fetchpriority="high", drops the reveal wrapper and its placeholder so nothing delays the paint, and registers the image's sources as <link rel="preload"> hints in the page head.

Use it only for images that are visible without scrolling. Marking several images eager competes for the same early bandwidth and slows down the one that matters.

SVG sources ​

An SVG cannot be resized by the resizer, so an SVG source is rendered as a plain <img> pointing at the original file, with the intrinsic width and height read from the file. Roles have no effect on an SVG.

Pre-generating the variants ​

The resized variants are built on the first request for each one. To warm them ahead of a launch or after a content update, run:

bin/magento catalog:images:pregenerate

The CMS responsive images source scans cms_page and cms_block content and the saved widget instances for both the directive and the widget, and generates the variants for every image it finds. See Pre-generating responsive images for the --async form and the rest of the command.