ESL Image Utils New

Lightweight helpers for use with native img and picture elements.

ESL Image Container Mixin

ESLImageContainerMixin (esl-image-container) is a custom attribute used to set an image container class once the image has loaded.

This mixin is intended to be added to the image container element (e.g., div, picture, etc.) but can also be added directly to the image element.

The mixin observes all images inside the host element. A ready class is applied to the host element when all images have finished loading (either successfully or with an error). An error class is applied to the host element if any image fails to load.

Configuration

The mixin uses a primary attribute, esl-image-container, with optional configuration passed as a JSON attribute value.

Configuration options:

  • readyCls (string) - class to apply to the target element when the image is loaded. Supports CSSClassUtils query.
    By default, the class img-container-loaded is applied.
  • errorCls (string) - class to apply to the target element if there is an image loading error. Supports CSSClassUtils query.
    By default, no error class is applied.
  • selector (string) - query selector to find the target image element.
    By default, the selector is img. Note: If the mixin is applied to the image element, the image itself will be checked against the selector anyway.

Usage

Apply the default img-container-loaded class to the image container once the image has loaded. In the most common use case, the host element is the container.

<div class="img-container img-container-16-9" esl-image-container>
  <img alt src="image.jpg"/>
</div>

or

<picture class="img-container img-container-16-9" esl-image-container>
  <source srcset="image.webp" type="image/webp">
  <img alt src="image.jpg"/>
</picture>

Apply the custom class loaded to the image container element when the image loads, and the class error if an image loading error occurs.

<div class="img-container" esl-image-container="{readyCls: 'loaded', errorCls: 'error'}">
  <img alt src="image.jpg"/>
</div>

Apply the custom class loaded directly to the image element when it loads.

<img alt src="image.jpg" esl-image-container="{readyCls: 'loaded'}"/>

Apply the custom class loaded to the direct parent of the image element when the image loads successfully. Note: The error class query is executed after the ready class query, so the error class could override the ready class.

<div class="img-container" esl-image-container="{readyCls: 'loaded', errorCls: '!loaded'}">
  <img alt src="image.jpg"/>
</div>

or simply

<div class="img-container" esl-image-container="{readyCls: '', errorCls: '!loaded'}">
  <img alt src="image.jpg"/>
</div>

ESL Image Container (CSS Only)

A set of common CSS classes to use with native images. Seamless integration with ESLImageContainerMixin defaults.

Main container & image classes

Source: esl-image-utils.container.less

  • img-container - mandatory container class (can also be applied to picture elements).
  • img-container-loaded (Automatic) - class applied to the container element when the image loads. Maintained by ESLImageContainerMixin.
  • img-stretch - class to apply to the img element to stretch the image to cover the container area.
  • img-cover - class to apply to the img element to cover the container area while maintaining aspect ratio.
  • img-contain - class to apply to the img element to fit (inscribe) the container area while maintaining aspect ratio.

Aspect Ratio Container Classes

Source: esl-image-utils.ratios.less

  • img-container-16-9 - aspect ratio 16:9 container class.
  • img-container-26-9 - aspect ratio 26:9 container class.
  • img-container-4-3 - aspect ratio 4:3 container class.
  • img-container-1-1 - aspect ratio 1:1 container class.

Image Fade-In Animation

Source: esl-image-utils.fade.less

  • img-fade - class to apply a fade-in animation on image load. Works with the img-container-loaded class.

Usage

<picture class="img-container img-container-16-9" esl-image-container>
  <source srcset="image.webp" type="image/webp">
  <img alt src="image.jpg" class="img-fade img-cover" loading="lazy"/>
</picture>