Image

Ready Added in 2.0.0

Speed up page loading times and decrease traffic by only loading images as they enter the viewport.

The image component emulates browser features of the <img> element, but for background images. This includes loading="lazy", srcset and sizes attributes as well as the <source> element from the <picture> element. This speeds up page loading times and decreases traffic by only loading background images as they enter the viewport. Optimized background images are served for different device widths and high resolution (retina) displays.

Usage

To apply this component, add the gls-img and the data-src attribute containing the image path for the background image to a div or any other element. By default, the background image will be lazy loaded as it enters the viewport when scrolling.

<div data-src="" gls-img>...</div>

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover gls-light" data-src="https://images.unsplash.com/photo-1490822180406-880c226c150b?fit=crop&w=650&h=433&q=80" gls-img>
  <h1>Background Image</h1>
</div>

Eager loading

To avoid lazy loading background images for the first visible viewport but still use other features of this component, add the loading="eager" parameter to the gls-img attribute.

<div data-src="" gls-img="loading: eager">...</div>

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover gls-light" data-src="https://images.unsplash.com/photo-1495321308589-43affb814eee?fit=crop&w=650&h=433&q=80" gls-img="loading: eager">
  <h1>Background Image</h1>
</div>

Srcset

To use the srcset feature for background images, just add the data-srcset attribute. Optionally, add the sizes attribute but without prefix.

<div data-src="" data-srcset="" sizes="" gls-img>...</div>

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover"
     data-src="https://images.unsplash.com/photo-1485627941502-d2e6429a8af0?fit=crop&w=650&h=433&q=80"
     data-srcset="https://images.unsplash.com/photo-1485627941502-d2e6429a8af0?fit=crop&w=650&h=433&q=80 650w,
                  https://images.unsplash.com/photo-1485627941502-d2e6429a8af0?fit=crop&w=1300&h=866&q=80 1300w"
     sizes="(min-width: 650px) 650px, 100vw" gls-img>
    <h1>Background Image</h1>
</div>

Picture sources

To use different image sources just like the <picture> element that contains <source> elements does, add the source attribute with srcset, media and type parameters.

<div sources="srcset: ____; media: ____" data-src="" gls-img>...</div>

<div sources="srcset: ____; type: ____" data-src="" gls-img>...</div>

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover gls-light"
     sources="srcset: https://images.unsplash.com/photo-1487837647815-bbc1f30cd0d2?fit=crop&w=650&h=433&q=80; media: (min-width: 1200px)"
     data-src="https://images.unsplash.com/photo-1546349851-64285be8e9fa?fit=crop&w=650&h=433&q=80"
     gls-img>
    <h1>Background Image</h1>
</div>

It’s possible to offer multiple image sources and also multiple resolutions for each source using srcset.

<div sources="srcset: ____; media: ____" data-src="" data-srcset="" sizes="" gls-img>...</div>

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover gls-light"
     sources="srcset: https://images.unsplash.com/photo-1464621922360-27f3bf0eca75?fit=crop&w=650&h=433&q=80 650w,
                      https://images.unsplash.com/photo-1464621922360-27f3bf0eca75?fit=crop&w=1300&h=866&q=80 1300w; 
              media: (min-width: 1200px)"
     data-src="https://images.unsplash.com/photo-1472803828399-39d4ac53c6e5?fit=crop&w=650&h=433&q=80"
     data-srcset="https://images.unsplash.com/photo-1472803828399-39d4ac53c6e5?fit=crop&w=650&h=433&q=80 650w,
                  https://images.unsplash.com/photo-1472803828399-39d4ac53c6e5?fit=crop&w=1300&h=866&q=80 1300w"
     sizes="(min-width: 650px) 650px, 100vw" gls-img>
    <h1>Background Image</h1>
</div>

Multiple sources can be defined using JSON syntax.

[
    {
        "srcset": "____",
        "media": "____"
    },
    {
        "srcset": "____",
        "type": "____"
    }
]

The JSON needs to be HTML encoded.

<div sources="[{&quot;type&quot;: &quot;____&quot;,
                &quot;srcset&quot;: &quot;____&quot;
               },
               {&quot;type&quot;: &quot;____&quot;,
                &quot;srcset&quot;: &quot;____&quot;
               }]"
     data-src="" gls-img>...</div>

This example offers alternative image formats like WebP and AVIF.

Background Image

<div class="gls-height-medium gls-flex gls-flex-center gls-flex-middle gls-background-cover"
     sources="[{&quot;srcset&quot;: &quot;https://utahhealthcare.github.io/gloss-docs/images/image-type.avif&quot;,
                &quot;type&quot;: &quot;image\/avif&quot;
                },
                {&quot;srcset&quot;: &quot;https://utahhealthcare.github.io/gloss-docs/images/image-type.webp&quot;,
                &quot;type&quot;: &quot;image\/webp&quot;
                }]"
        data-src="https://utahhealthcare.github.io/gloss-docs/images/image-type.jpg"
        gls-img>
    <h1>Background Image</h1>
</div>

Component options

Any of these options can be applied to the component attribute. Separate multiple options with a semicolon. Learn more

Option	Value	Default	Description
`dataSrc`	String	''	The image’s `src` attribute.
`dataSrcset`	String	false	The image’s `srcset` attribute.
`sizes`	String	false	The image’s `sizes` attribute.
`width`	String	false	The image’s `width` attribute. It will be used to determine the placeholder’s width and the position of the image in the document.
`height`	String	false	The image’s `height` attribute. It will be used to determine the placeholder’s height and the position of the image in the document.
`offsetTop`	String	‘50vh’	The offset increases the viewport’s bounding box vertically before computing an intersection with the image.
`offsetLeft`	String	0	The offset increases the viewport’s bounding box horizontally before computing an intersection with the image.
`target`	String	false	A list of targets whose bounding boxes will be used to compute an intersection with the image. Defaults to the image itself.

dataSrc is the Primary option, and its key may be omitted if it’s the only option in the attribute value.

JavaScript

Learn more about JavaScript components.

Initialization

Gloss.img(element, options);

Note The Image component keeps records of already loaded images in the Session Storage. That’s how it tries to determine if an image is already cached. A cached image is loaded immediately, without the lazy loading mechanism to prevent any rendering flashes. Prior to testing the Image component, make sure to clear these records from your browser’s Session Storage.