All rules

Sheath rule

perf-lazy-load-images

Images should use loading="lazy" for deferred loading.
Package
Core
Category
Performance
Default severity
info by default
Auto-fix
Auto-fix available

(dangerous)

#Why

loading="lazy" tells the browser to defer an image until it approaches the viewport. On a long page most images are never scrolled to, so those requests never happen at all, and the ones that matter are not queued behind them.

It is a browser feature, so there is no library to load and nothing to initialize.

#Examples

#Bad

<!-- Images without lazy loading -->

<img src="/images/photo1.jpg" alt="Photo 1">

<img src="/images/photo2.jpg" alt="Photo 2">

<img src="/images/photo3.jpg" alt="Photo 3">

#Good

<!-- First image eager (above the fold) -->

<img src="/images/hero.jpg" alt="Hero" loading="eager">



<!-- Other images lazy loaded -->

<img src="/images/photo1.jpg" alt="Photo 1" loading="lazy">

<img src="/images/photo2.jpg" alt="Photo 2" loading="lazy">

<img src="/images/photo3.jpg" alt="Photo 3" loading="lazy">



<!-- High priority image (skip lazy loading) -->

<img src="/images/important.jpg" alt="Important" fetchpriority="high">

#Loading Values

Choose the loading value according to when the image should be fetched.

Value Behavior
lazy Defer loading until near viewport
eager Load immediately (default behavior)

Those are the only valid static keywords. Empty values, auto, and unknown keywords use eager behavior in browsers. Below-fold images are reported for all eager behavior, including an explicit loading="eager" value.

#Options

Use these options to protect above-the-fold images and exclude selected URLs.

Option Type Default Description
skipAboveFold bool true Skip first image (likely above fold)
excludePatterns array [] URL patterns to exclude 
<?php



'perf-lazy-load-images' => ['warning', [

    'skipAboveFold' => true,

    'excludePatterns' => ['logo', 'hero', 'banner'],

]],

#When Not to Lazy Load

  • Above-the-fold images: Hero images, logos, main content images
  • LCP images: The largest contentful paint element
  • Critical images: Images essential for initial page experience
  • Small icons: Overhead not worth it for tiny images

#Auto-fix

Auto-fix adds loading="lazy" to images, or replaces an invalid static loading attribute with it:

<!-- Before -->

<img src="/images/photo.jpg" alt="Photo">



<!-- After -->

<img src="/images/photo.jpg" alt="Photo" loading="lazy">

The fix is dangerous and requires --dangerous, because it changes when the browser requests and renders the image.

#Notes

  • Skips images with fetchpriority="high" (intentionally eager)
  • By default, skips the first image (likely above the fold)
  • Images inside capture-only Blade sections and stacks are excluded from source-order placement because their output position is determined by the layout's @yield or @stack. A section closed with @show remains live
  • Checks <img> elements; it does not currently inspect iframes
  • Missing loading is not reported when image attributes are generated dynamically, such as with {{ $attributes }} or @if

#References

#Related Rules