What's on this page

• With the html function
• With filters
  • Dominant color
  • Blurred preview

Display image placeholders while loading

Images are often the heaviest resources of a page. While they load, Cecil can fill their space with a dominant color or a Low-Quality Image Placeholder (LQIP), to avoid empty blocks and improve perceived performance.

With the html function

The simplest way is the placeholder option of the html function, set to color or lqip:

{{ html(asset('images/photo.jpg'), {alt: 'Description', loading: 'lazy'}, {placeholder: 'lqip'}) }}

To apply it to every image rendered with html, set a default in cecil.yml:

layouts:
  images:
    placeholder: color # `color` or `lqip`

With filters

For a custom markup, use the filters directly:

• lqip: returns a 100x100 px, 50% blurred, version of the image as a data URL
• dominant_color: returns the dominant hexadecimal color of the image

Dominant color

{% set image = asset('images/photo.jpg') %}
<img src="{{ url(image) }}" width="{{ image.width }}" height="{{ image.height }}" alt="Description" loading="lazy"
  style="background-color: {{ image|dominant_color }};">

Blurred preview

{% set image = asset('images/photo.jpg') %}
<img src="{{ url(image) }}" width="{{ image.width }}" height="{{ image.height }}" alt="Description" loading="lazy"
  class="placeholder" style="background-image: url({{ image|lqip }});">

Stretch the preview over the image area with CSS:

img.placeholder {
  max-width: 100%;
  height: auto;
  background-size: cover;
  background-repeat: no-repeat;
}

The background is visible until the real image is loaded and painted over it.