Blazy

Blazy provides lazy loading and media optimization for Drupal using bLazy, Intersection Observer API, and native browser lazy loading.

It reduces initial page weight and HTTP requests by deferring off-screen media. This can improve perceived performance, particularly on media-heavy pages and mobile devices. Core Web Vitals integration was introduced in 2022, most notably via Loading priority and Preload options.

Blazy supports images, responsive images, iframes, background images, and selected media integrations. It is opt-in and can be enabled via field formatters, Views styles, filters, or Layout Builder.

Requirements

• PHP 8.2 and Drupal 11.0 specific for 4.x.
• Core Media
• Core Layout Discovery (for Blazy Layout sub-module)

Versions

• 4.x: Drupal 11 - 12+
  Blazy 3.x and 4.x are different in codebase, but similar in functionality. Upgrading requires reading the CR, and may be straight forward if hardly customizing hooks or public API.
• 3.x: Drupal 9.4 - 11+
  Blazy 2.x and 3.x are designed to be identical, except for version numbers and later fixes. Upgrading should be straight forward.

Features

• Native lazy loading support with graceful fallback
• Intersection Observer support
• Works with IMG, PICTURE, IFRAME, SVG, and CSS background images; or mixed-media
• Core Media, oEmbed, and Responsive Image integration, and a few Media contribs
• Optional lightbox integrations
• Views style plugin (Blazy Grid), and Views fields
• No-JavaScript compatibility, AMP, static archive sites like Tome.
• Layout Builder dynamic layouts

Blazy does not override all images automatically. It is enabled per formatter, filter, View, or layout configuration.

Installation and Update SOP

• Composer installation guide
• Drupal Module Installation Manual
• Update SOP

Usage

• Field formatter — Configure via Manage display.
• Views style (Blazy Grid) — Select under Views format options.
• Blazy Filter — Enable in Text formats.
• Blazy Layout — Enable sub-module for Layout Builder integration.
• Global options — /admin/config/media/blazy.

Performance

Performance impact depends on page composition. On media-heavy pages, deferring off-screen assets can significantly reduce initial page size and HTTP requests.

How much can Blazy help performance?

• Before core native lazy loading:
  In internal benchmarks on image-heavy pages, total transferred size was reduced from approximately 14 MB to 3 MB (e.g., large slideshow images with many thumbnails), HTTP requests from about 200 to 20, and load time from roughly 30 seconds to 3seconds. Performance grades in tools such as GTmetrix improved accordingly. Results vary by site and configuration.
• With core native lazy loading:
  Native lazy loading covers standard image and iframe use cases. Additional gains from Blazy may be observed in scenarios involving sliders, background images, iframes with media player preview, third-party HTML oEmbeds, or stricter Core Web Vitals (e.g., LCP) requirements.

Blazy can be combined with other optimization strategies such as caching, asset aggregation, AdvAgg, and CDN usage for broader performance improvements.

FAQ

Is Blazy deprecated by native lazy loading?

No. Native lazy loading currently supports images and iframes. Blazy extends this with additional media integrations, layout tools, fallback handling, and progressive enhancement strategies.

If I only need basic lazy loading, is Blazy necessary?

For simple use cases, native lazy loading may be sufficient. Blazy is intended for projects requiring broader media integration, grid layouts, lightboxes, or extended compatibility.

Why is Media required in modern branches?

Core Media provides a consistent way to manage images, videos, and remote media. Blazy integrates with Media to support responsive and reusable media workflows.

Why do other modules depend on Blazy?

Blazy provides shared lazy loading and grid functionality that can be reused by other modules to reduce duplication and maintain consistent behavior.

Troubleshooting

See the Troubleshooting guide.

Upgrading

Always review the Update SOP before upgrading.

General recommendations:

• Back up your site before upgrading.
• Ensure Drupal core is updated first.
• Keep Blazy sub-modules on matching branch versions.
• Clear caches after each upgrade step.

Upgrade Path Overview

• 1.x → 2.x → 3.x → 4.x (sequential upgrade required)
• 2.x → 3.x → 4.x
• 3.x → 4.x

Major versions should be upgraded sequentially. Skipping major branches is not supported.

Upgrading to 4.x

Blazy 4.x continues modernization for current Drupal core versions and removes deprecated APIs from 3.x.

• Update Drupal core to a supported version.
• Review Blazy 4.x Revamp and Deprecation if working with Blazy API or public methods.
• Install Upgrade Status for thorough review.
• Resolve any deprecation warnings before proceeding.
• Update Blazy and all related sub-modules to their latest 3.x release.
• Require 4.x via Composer.

Composer Upgrade Example (3.x → 4.x)

composer require drupal/blazy:^4.0 -W
drush cr
drush updb
drush cr

If using additional Blazy-related modules, upgrade them in the same Composer operation to avoid version mismatches.

composer require drupal/blazy:^4.0 drupal/slick:^4.0 drupal/slick_views:^4.0 -W -n

After upgrading:

• Review field formatters and Views displays.
• Re-save configurations only if any issues.
• Verify custom integrations against removed deprecated APIs or CSS changes.

Common Issues

• Cache not cleared after code updates.
• Mismatched sub-module branch versions.
• Custom code relying on deprecated methods or services removed in 4.x.

If issues occur, review the status report page and recent log entries after clearing cache.