loading=lazy: which images need it and which must not

What loading=“lazy” does

loading="lazy" on an <img> tells the browser to defer the request until the image is near the viewport. It is native, needs no JavaScript, and is supported in every current browser.

It is the wrong attribute for anything visible on arrival. Lazy-loading the largest visible image delays the request that Largest Contentful Paint is measured on, so a page can get slower by adding it. The rule of thumb is lazy below the fold, eager or nothing above it.

What squirrel checks

The rule runs on every crawled page. It takes every img[src] in document order, treats the first above_fold_count of them as above the fold, and examines the rest. Images with a data: source are skipped.

• Info when the page has no images. Message: No images found.
• Pass when there are no images past the fold count. Message: Few images on page - lazy loading not critical.
• offscreen-images-not-lazy warns for below-fold images whose loading value is neither exactly lazy nor exactly eager, which covers an absent attribute, an empty one and any misspelling. Message: 7 below-fold image(s) without lazy loading, listing up to ten filenames. Severity warning, weight 5.
• lazy-loading-used passes when any below-fold image is lazy. Message: 12 image(s) use lazy loading.
• eager-below-fold reports info for below-fold images explicitly set to eager. Message: 2 below-fold image(s) explicitly set to eager, noted as possibly intentional.
• offscreen-lazy reports info when nothing was flagged and nothing was lazy, which happens when every examined image is eager or every one was skipped as a data URI. Message: No lazy loading configured - consider adding loading='lazy'.

Document order is a proxy for position, not a measurement. An image that appears late in the markup but is positioned at the top of the viewport by CSS is treated as below the fold.

Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.

How to fix it

<img src="/hero.jpg" width="1200" height="600" alt="…" fetchpriority="high" />
<img src="/gallery-1.jpg" width="600" height="400" alt="…" loading="lazy" />

Leave the hero image alone, or mark it fetchpriority="high", and add loading="lazy" to everything the visitor has to scroll to. A component that renders a list of images can apply it to every item after the first row.

Raise above_fold_count for a page whose first screen genuinely shows more images than the default three.

Options

Configuration example

[rule_options."images/offscreen-lazy"]
above_fold_count = 6

Enable / disable

Disable this rule

[rules]
disable = ["images/offscreen-lazy"]

Disable all Images rules

[rules]
disable = ["images/*"]

Enable only this rule

[rules]
enable = ["images/offscreen-lazy"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• images/lazy-loading: the page-wide count of lazy elements, including iframes.
• perf/lazy-above-fold: the opposite mistake, lazy-loading the LCP image.
• perf/lcp-fetchpriority: marking the image that should load first.
• images/dimensions: the width and height that stop lazy images shifting the layout.

Images findings ship in every audit next to the SEO, performance and agent experience rules. See Core Web Vitals for how an agent works through a report.

References

• Browser-level image lazy loading, web.dev
• Optimize Largest Contentful Paint, web.dev

Check your site

Run squirrel audit https://example.com and open the Images section of the report. Every below-fold image without the attribute is listed by filename. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.