lazyimg

Lazy image loading with superpowers.

Lazy loading for images via lazySizes
No-Script/No-JS safe: Fallback to browser's native method
Image previews: Blur-up Low Quality Image Placeholder (LQIP) technique
Automatic responsive image resizing
Multiple supported renderers (e.g. LQIP with WebP support)

Used by the Osprey Delight theme, which directly benefits from this module!

Quickstart

Go get it

Initialize Hugo's mod system on your site (replace username and repo):

hugo mod init github.com/{username}/{repo}

Add module to site's config (e.g. config.yaml):

module:
  imports:
  - path: github.com/hugo-mods/lazyimg

Get the module (also upgrades existing one):

hugo mod get -u

Usage

Put the images which you want to use in the assets directory of your project. They should be in a high resolution and will be resized automatically.
Add the following boilerplate setup code to your site's <head>:

{{ partial "lazyimg-setup" }}

Load the image:
- In a template file: Call the lazyimg partial where you would usually use an img tag:
```
{{ partial "lazyimg" "awesome-image.jpeg" }}
```
- In a content file: Call the lazyimg shortcode:
```
{{< lazyimg img="awesome-image.jpeg" >}}
```

For more advanced usage, please refer to the exampleSite for a practical approach or continue reading the theory as described in the next section.

Configuration

Please check out the example site's config for all options.

Resizers

Allowed values for resizer:

Name	Description
`simple`	Produces default image with `maxSize`, LQIP with `lqipSize`.
`responsive`	Produces default image with `maxSize`, LQIP with `lqipSize` and responsive images based on `responsiveSizes`.
`auto`	Produces default image with `maxSize`, LQIP with `lqipSize` and partitions (max. of 5) responsive sizes based on an algorithm.

Renderers

Allowed values for renderer:

Name	Description
`simple`	Responsive image lazy-loading.
`lqip`	Responsive image lazy-loading with LQIP blur-up preview. Use with `lazyimg.css`.
`lqip-webp`	Responsive image lazy-loading `lqip` with additional WebP support.
`native`	Browser-native loading via `loading="lazy"`. Does not require JS, used as fallback in other renderers when `noscript` is true.

CSS

The lazyimg.css is the recommended boilderplate CSS. It contains rules for blur-up animation, hiding "broken image icon" on lazy-loading and no-js selector.

Disabled JS

Support for disabled JS can be accomplished by adding a "no-js" class to your html root tag, e.g.:

<html lang="en" class="no-js"> <!-- ... --> </html>

Then, to remove the class when the client indeed supports JS, add the following script:

<script>document.documentElement.className = "js"</script>

Alternatively, use lazyimg-setup-nojs instead of lazyimg-setup which will do the replacement for you. In this case, you only need to add the no-js class to your html root tag.