Images

There are a number of strategies for including images, depending on the required quality (either original, or a bit lower quality but with better compression hence smaller file size using webp), and position on the page where they are placed.

Images are added with the standard <img> tag, however to enable processing by Splendid, the tag needs to be closed with a />. If it is not closed (i.e., is written as void tag), the standard HTML is kept without any processing.

<img src="img/example.jpg" alt="Image"/> <!-- processed -->

<img src="img/example.jpg" alt="Image"> <!-- NOT processed -->

Alt Attribute

The alt attribute is essential for SEO and users with screen readers, therefore there will be a warning displayed when it is missing (on processed tags).

Paths

When specified paths to the image begin with . such as <img src="./img/example.jpg" />, they will be resolved to the location relative to the file in which they are referenced. When there is no leading ., such as <img src="img/example.jpg" />, the path is relative to the Splendid app directory.

Lazy-Loading

One of the advantages of the <img> component is that images can be loaded only when user scrolls them into view. This saves bandwidth and improves the loading time as the page does not have to wait for image data to be downloaded. Lazy-loading is enabled by default.

<img src="img/my-img.jpg" alt="My Image" />

This will generate html similar to the following one:

Because lazy-loading requires JavaScript, there's a <noscript> tag added next to the image placeholder, which will be displayed if the user has JS disabled.

Above Fold

Some images will be displayed above fold, i.e. immediately visible to the user. To make sure they are loaded straight away when the page opens without waiting for JavaScript to evaluate, the above-fold attribute should be added.

<img src="img/my-img.jpg" alt="My Image" above-fold />

In this case, there will be no <noscript> tag as no JavaScript is required.

Placeholder

Before the image is loaded, the browser does not know its dimensions, therefore an empty space is displayed, which once updated makes the page jump. To avoid this jumping behavior, a placeholder should be added — an empty SVG image with the dimensions of the image. This way, there is no jumping of the content.

<img src="img/my-img.jpg" alt="My Image" placeholder-auto />

When adding the placeholder-auto attribute, Splendid will look up the dimensions of the image using the image processing library and generate the placeholder. The dimensions can also be specified manually with placeholder-width and placeholder-height attributes.

<img src="img/my-img.svg" alt="Photo"
  placeholder-width="300px" placeholder-height="200px" />

The standard technique of setting width and height on the image tag like <img width="500" height="500" src="img/dimensions.jpg"/> does not prevent the jumping behaviour as we've found out after testing, therefore the SVG needs to be used.

Responsive WebP

Splendid can generate webp images by calling cwebp on the local machine. This means that this binary needs to be installed. After that, the webp attribute needs to be set for automatic generation of webp images and the picture element that would display the image according to the screen resolution.

<img webp="photo" src="../img/photo.jpg" alt="Picture" />

Help Center