Blazy
Provides media lazy loading using bLazy, Intersection Observer API, or browser native lazy loading to optimize bandwidth and server requests.
blazy
Install
composer require 'drupal/blazy:^3.0'
Overview
Blazy is a comprehensive media lazy loading solution for Drupal that integrates with the bLazy library, Intersection Observer API, and browser native lazy loading to delay loading of below-fold images until they are needed. This saves bandwidth and reduces server requests, resulting in faster load times for users.
The module supports a wide variety of media types including core images, responsive images, local and remote videos, SVG files, and iframes. It provides field formatters for displaying media with lazy loading, grid layouts (CSS3 Columns, Flexbox, Native Grid), and lightbox integrations with Colorbox, Magnific Popup, PhotoSwipe, and built-in Blazybox/Flybox lightboxes.
Blazy serves as a foundation for many other Drupal modules including Slick, Splide, GridStack, Mason, and others, providing a unified API for media handling, grid displays, and lightbox functionality.
Features
- Lazy loading for images, responsive images, videos, iframes, and SVG using Intersection Observer API or browser native lazy loading
- Multi-serving lazyloaded images with multi-breakpoint CSS background support
- Field formatters for Image, Media, Entity Reference, File/SVG, OEmbed, and Text fields
- Grid layouts: CSS3 Columns, Grid Foundation, Flexbox, and Native Grid with CSS3 Masonry
- Lightbox integrations: Colorbox, Magnific Popup, PhotoSwipe, plus built-in Blazybox and Flybox
- Blazy Filter for inline images and iframes in text content with shortcode support
- Views integration with Blazy Grid style plugin and Views fields for File and Media
- Image effects including Blur placeholder effect with client-side and localStorage caching options
- Responsive image support with 1px placeholder optimization
- SVG support with inline rendering and sanitization (requires enshrined/svg-sanitize library)
- WEBP support with polyfill for older browsers
- Aspect ratio support with fluid and fixed ratios
- Works without JavaScript for static/archived sites (AMP, Tome, HTTrack)
- Third-party formatter settings to enable Blazy on any image formatter
- Caption support with fieldable lightbox captions
Use Cases
Lazy Loading Image Galleries
Use Blazy Image formatter on multi-value image fields to create lazy-loaded image galleries. Enable a lightbox (Colorbox, Magnific Popup, PhotoSwipe) under 'Media switcher' option. Select 'Blazy Grid' style with desired grid type (Native Grid, Flexbox, CSS Columns) for automatic responsive gallery layouts.
Video/Media Galleries with Poster Images
Use Blazy Media formatter on entity reference fields pointing to Media. Configure 'Media switcher' as 'Image to iframe' to show poster images that switch to video players on click. Add field_media_image to Video and Remote video bundles for custom poster images.
Responsive Image Optimization
Enable 'Responsive image 1px placeholder' in Blazy UI settings and select a Responsive image style in Blazy formatter. This uses 1px data URI placeholder to prevent downloading fallback images while maintaining responsive image behavior.
Blur Placeholder Effect
Select 'blur' under Image effect in Blazy UI settings. Configure Thumbnail style in formatter for blur placeholder size. Enable 'Use client-side blur' and 'Store blur in localStorage' for optimal performance.
Views Grid Display with Lightbox
Create a View with Blazy Grid style plugin under Format. Add a Views field with Blazy formatter (blazy_file or blazy_media). Configure lightbox in the formatter. The grid automatically groups items for lightbox gallery navigation.
Inline Content Lazy Loading
Enable Blazy filter at /admin/config/content/formats on desired text format. Use shortcodes for advanced features: [blazy grid="nativegrid:2-3-4"]..images..[/blazy] for grids, or [blazy data="node:44:field_media" /] to embed entity media fields inline.
Layout Builder with Media Backgrounds
Enable Blazy Layout submodule. In Layout Builder, add Blazy Layout section. Configure region backgrounds using Media Library (requires Media library form element module) or by adding Content block fields with Blazy formatter and 'Use CSS background' enabled.
SVG with Inline Rendering
Install enshrined/svg-sanitize library via Composer. Use File field type for SVG uploads. Apply Blazy File formatter with inline SVG option enabled for direct SVG rendering with sanitization.
Tips
- Match module versions across Blazy and its sub-modules (Slick, Splide, etc.) - DEV with DEV, stable with stable - to avoid compatibility issues.
- Use Blazy Grid Views style with 'Blazy formatter' fields for automatic lightbox gallery grouping across Views results.
- For performance, enable 'No JavaScript > Lazyload' in Blazy UI if only using browser native lazy loading and don't need blur effects or CSS backgrounds.
- The blazy() helper function provides quick access to BlazyManager service in procedural code.
- Use hook_blazy_settings_alter() to add custom aspect ratios without inline padding styles by setting blazies css.ratio values.
- Blazy Filter shortcodes support entity embedding: [blazy data="node:123:field_media" /] renders a node's media field inline.
- For development, check browser console for 'blazy' object which exposes debugging information.
- Blazy automatically handles Content Security Policy through its CspSubscriber event subscriber.
- Use 'By delta' option in formatter to map specific media items from a multi-value field to different Layout Builder regions.
Technical Details
Admin Pages 1
/admin/config/media/blazy
Configure global Blazy settings for lazy loading behavior, image effects, polyfills, and IntersectionObserver API options.
Permissions 1
Hooks 9
hook_blazy_attach_alter
Alters Blazy attachments to add custom libraries, drupalSettings, or JS templates.
hook_blazy_lightboxes_alter
Alters available lightbox options for the Media switch select in formatter settings.
hook_blazy_alter
Alters individual Blazy item output to support custom lightboxes or modify image/video rendering.
hook_blazy_build_alter
Alters entire Blazy output to add wrappers, prefixes, or modify grid containers.
hook_blazy_base_settings_alter
Alters blazy-related formatter base settings to add custom options across all formatters.
hook_blazy_settings_alter
Alters blazy settings inherited by all child elements. Called for formatters and Views.
hook_blazy_item_alter
Alters individual blazy item settings, useful for mixed media content customization.
hook_blazy_form_element_alter
Alters blazy-related formatter form elements before finalization. Best place to add new form items.
hook_blazy_complete_form_element_alter
Alters blazy-related formatter form elements after finalization. Useful for modifying existing elements.
Troubleshooting 7
Check if using a scrolling container (modal, parallax). Add container CSS selector to 'Scrolling container' in Blazy UI settings. Try unchecking 'Disconnect' under IO settings. Ensure images have proper dimensions or aspect ratio configured.
Enable 'Load invisible' option in Blazy UI settings under 'Blazy settings' section to load hidden elements.
Views sanitization strips data:image URIs. Configure 'Placeholder' field in Blazy UI with a URL path to blank.svg or blank.gif file placed in Drupal web root.
Ensure Thumbnail image style is configured in formatter settings. Check 'Blur min-width' is not set too high. Verify aspect ratio is configured to prevent collapsed images.
When using Views, uncheck 'Use field template' under Style settings. This allows Blazy to group items into a single gallery rather than per-field galleries.
Install SVG Sanitizer library: composer require enshrined/svg-sanitize. Clear caches after installation.
Install DOMPurify library: composer require npm-asset/dompurify. Place in /libraries/dompurify/dist/purify.min.js. Without it, only basic server-side sanitization is applied.
Security Notes 5
- The 'administer blazy' permission is marked as 'restrict access: true' - only grant to trusted administrators.
- SVG inline rendering requires the enshrined/svg-sanitize library for XSS protection.
- Lightbox HTML captions should use DOMPurify library for client-side sanitization of user-generated content.
- Blazy Filter's 'Trust data URI' option has security implications - only enable for trusted content editors.
- When using [blazy data="..."] shortcodes in text content, ensure the text format is restricted to trusted users.