- 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!
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/lazyimgGet the module (also upgrades existing one):
hugo mod get -u- Put the images which you want to use in the
assetsdirectory 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
lazyimgpartial where you would usually use animgtag:
{{ partial "lazyimg" "awesome-image.jpeg" }}- In a content file: Call the
lazyimgshortcode:
{{< lazyimg img="awesome-image.jpeg" >}} - In a template file: Call the
For more advanced usage, please refer to the exampleSite for a practical approach or continue reading the theory as described in the next section.
Please check out the example site's config for all options.
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. |
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. |
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.
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.