Lazy-load
Enables lazy-loading for images and iframes to improve page load performance using the lazysizes JavaScript library.
lazy
Install
composer require 'drupal/lazy:^4.0'
composer require 'drupal/lazy:8.x-3.16'
Overview
The Lazy-load module provides a comprehensive solution for lazy-loading images and iframes in Drupal. It defers the loading of off-screen images and iframes until they are about to enter the viewport, significantly improving initial page load times and reducing bandwidth usage.
The module supports multiple integration methods: text filters for inline images and iframes in formatted text fields, field formatter settings for image fields, and custom field formatters for Views. It uses the high-performance lazysizes JavaScript library which provides SEO-friendly lazy loading with automatic detection of visibility changes.
Key capabilities include support for responsive images with picture/srcset, native browser lazy-loading fallback via the loading="lazy" attribute, placeholder images with optional data URI embedding, CSS transition effects, automatic disabling on AMP pages, and flexible path-based visibility controls.
Features
- Lazy-loads images and iframes using the lazysizes JavaScript library for high performance and SEO-friendly loading
- Supports inline images and iframes in formatted text fields via configurable text filter
- Integrates with image field formatters including Image, Responsive Image, Colorbox, and Media Thumbnail
- Provides dedicated Image (Lazy-load) and Responsive image (Lazy-load) field formatters for use with Views
- Supports native browser lazy-loading via loading="lazy" attribute as an alternative to JavaScript
- Allows placeholder images with optional data URI embedding for inline base64 placeholders
- Offers CSS transition effects for smooth image loading animations
- Automatically disables lazy-loading on AMP pages
- Provides path-based visibility controls to enable/disable lazy-loading on specific pages
- Supports 24 lazysizes plugins for extended functionality including blur-up, object-fit, video-embed, and more
- Allows elements to skip lazy-loading by adding a configurable skip class
- Provides multiple hooks for theme/module customization of field formatters, CSS styles, and settings
Use Cases
Improving page load performance for image-heavy pages
Enable lazy-loading on image fields for content types that contain many images, such as galleries, portfolios, or product listings. This defers loading of off-screen images until users scroll to them, significantly reducing initial page load time and bandwidth usage.
Lazy-loading embedded videos and iframes
Enable the lazy-loading text filter with iframe support for text formats used in body fields. This defers loading of embedded YouTube videos, maps, and other iframe content until users scroll to them, improving initial page performance especially on pages with multiple embedded videos.
Using placeholder images for better perceived performance
Configure a placeholder image (such as a tiny transparent GIF or a blurred low-resolution version) to display while the actual image loads. This prevents layout shift and provides visual feedback that content is loading. Use the data URI option to embed small placeholders directly in HTML.
Views with lazy-loaded images
Use the dedicated Image (Lazy-load) or Responsive image (Lazy-load) field formatters in Views displays. These formatters automatically enable lazy-loading without requiring third-party settings configuration, making it easy to add lazy-loading to Views that display many images.
Disabling lazy-loading on specific pages
Use the visibility settings to disable lazy-loading on pages where it's not needed or could cause issues, such as RSS feeds, print-friendly pages, or pages with images that must load immediately above the fold.
Native lazy-loading for modern browsers
Enable the 'Prefer native lazy-loading' option to use the browser's built-in lazy-loading feature (loading="lazy" attribute) for browsers that support it. This provides lazy-loading without requiring JavaScript and may offer better performance in supported browsers.
Tips
- Use the Preview tab in module settings to test that lazy-loading is working correctly - scroll down past the spacer to see the preview image load
- For the best user experience, combine lazy-loading with responsive images to serve appropriately sized images to different devices
- The blur-up plugin can provide a nice visual effect by showing a blurred low-resolution placeholder that transitions to the full image
- Elements can be excluded from lazy-loading by adding the skip class (default: no-lazy) to the element or its parent
- When using Views, prefer the dedicated lazy-load formatters over third-party settings for simpler configuration
- Monitor Core Web Vitals (LCP, CLS) after enabling lazy-loading to ensure it improves rather than harms perceived performance
- Consider enabling native lazy-loading if your audience primarily uses modern browsers, as it requires no JavaScript
Technical Details
Admin Pages 1
/admin/config/content/lazy
Configure global lazy-loading settings for images and iframes across the site. This page shows which text formats and fields currently have lazy-loading enabled and provides comprehensive configuration options for the lazysizes library.
Permissions 1
Hooks 4
hook_lazy_field_formatters_alter
Alters the list of enabled field formatters that support lazy-loading. Use this hook to add custom image-based field formatters.
hook_lazy_default_styles_alter
Overrides the default CSS styles that are injected for lazy-loading classes (lazyload, lazyloaded).
hook_lazy_effect_styles_alter
Overrides the default CSS transition effect styles. Only applies when the 'Enable default CSS effect' option is checked.
hook_lazy_settings_alter
Alters the Lazy module settings. Can be used to override settings per environment or condition.
Troubleshooting 5
Verify that: 1) The lazysizes library is installed at the configured path (/libraries/lazysizes by default), 2) Lazy-loading is enabled for the text format or field formatter being used, 3) The current page is not in the disabled paths list, 4) The current page is not an admin page (if admin disable is enabled), 5) Elements don't have the skip class (no-lazy by default).
Download the lazysizes library from https://github.com/aFarkas/lazysizes/releases and place it in /libraries/lazysizes, or install via Composer with 'composer require bower-asset/lazysizes'. Ensure the folder name is exactly 'lazysizes' and contains lazysizes.min.js.
Either configure a placeholder image URL that matches the aspect ratio of your images, or use the placeholder_style option on field formatters to generate properly sized placeholder images. Consider enabling a small image style as the placeholder to maintain dimensions.
Use hook_lazy_field_formatters_alter() in your custom module to add your field formatter's machine name to the list of supported formatters.
Enable the 'Enable default CSS effect' option in the module settings to add smooth opacity transitions when images load. The default effect fades images in over 2 seconds.
Security Notes 3
- The module safely handles file paths and validates that library paths start with / or https:// to prevent path traversal attacks
- When using an external CDN for the lazysizes library, ensure it is from a trusted source as the JavaScript will execute on your site
- The text filter properly sanitizes DOM manipulation to prevent XSS when processing inline images and iframes