ESL Image

ESLImage - a custom element, that provides flexible ways to include images on web pages. Was originally developed as an alternative to <picture> element, but with more features inside.

Supported Features:

  • Different rendering modes:
    • cover - renders the image via background-image CSS property, background-size is cover by default, width and height are 100% by default;
    • safe-ratio - renders the image via background-image CSS property, but also sets height using padding-top: {aspectRatio}%; trick;
    • fit - renders the image using inner <img> element;
    • origin - renders the image using inner <img> element, sets width/height attributes using image's original size;
    • inner-svg - renders svg content inside (the content is loaded via XHR request).
  • Lazy loading modes:
    • none - image starts loading immediately;
    • manual - starts loading image when a marker is provided manually;
    • auto - image starts loading only if it's visible and is inside or close to browser viewport area (determined using Intersection Observer API).
  • ESLMediaQuery - special syntax that allows defining different sources for different media queries. Supports media-query shortcuts.
  • Marker class. ESL Image can add a specific class on the specified parent element when the image is ready. ESL Image itself also has markers that indicate its state.
  • Provides events on state change (also supports inline syntax, e.g. <esl-image-tag onload="">).
  • Attributes observing.
  • A11y.

Accessibility behaviour

ESL Image uses 'img' role if the role is not explicitly provided. If the role is 'img' then alt attribute is used as the aria-label for the image. In case alt is not provided then an empty value is used as a fallback. data-alt is considered a legacy attribute and is used only when the image was connected to DOM without alt or aria-label attribute.

Attributes:

  • data-src - src paths with query conditions. See ESLMediaQuery (watched value)

  • data-src-base - base src path for paths described in data-src (watched value)

  • alt - alt image text (watched value)

  • data-alt (Deprecated) - alt image text, not observable

  • mode - rendering mode. Default - save-ratio (watched value):

    • origin - save origin image size (use inner img tag for rendering);
    • fit - use inner img, but do not force its width;
    • cover - do not set self width/height; use 100% w/h of the container (use background-image for rendering);
    • save-ratio - fill 100% of container width and set the self height according to image ratio (use background-image for rendering);
    • inner-svg - load an SVG content via XHR request and render it inside.

  • lazy (optional) - enable lazy loading:

    • auto - IntersectionObserver mode: image starts loading as soon as it becomes visible in visual area
    • manual - start loading when lazy-triggered marker is set manually

  • refresh-on-update [boolean] (optional) - Always update the original image as soon as image source is changed

  • inner-image-class (optional) - class to mark and search the inner image, 'inner-image' by default

  • container-class (optional) - class that will be added to the container when the image is ready

  • container-class-state (optional) - image state in which the container will be marked with container-class (can be 'ready', 'loaded' or 'error')

  • container-class-target (optional) - ESLTraversingQuery to find the target to add container-class to ('::parent' by default).

NOTE: ESL Image supports title attribute like any HTML element, no additional reflection for that attribute is needed - it will work correctly according to HTML5.* REC

Readonly Attributes

  • ready [boolean] - appears when the image is ready (either loaded or failed to load)
  • loaded [boolean] - appears when the image is loaded for the first time
  • error [boolean] - appears when current image failed to load

API

  • triggerLoad - shortcut function for manual adding lazy-triggered marker
  • currentSrc - image URL that is currently in use

Events

  • ready - emits when the image is ready (either loaded or failed to load)
  • load - emits when the image is loaded (also when the path is changed)
  • error - emits when the current source failed to load.