=== Smart LazyLoad – Lazy Load Images, Videos and Iframes ===
Contributors: jumedeenkhan, mozedia
Donate link: https://buymeacoffee.com/jumedeenkhan
Tags: lazyload, lazy load, lazy loading, lazy load images, performance
Requires at least: 5.8
Requires PHP: 7.4
Tested up to: 7.1
Stable tag: 3.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The best lazy load plugin for WordPress. Lazy loading images, videos, and iframes to improve page speed, performance, and Core Web Vitals scores.

== Description ==

**Smart LazyLoad** is a free, simple, and lightweight lazy loading plugin. Lazy load WordPress images, videos, and iframes to improve page speed, website performance, and **Core Web Vitals** scores.

Most lazy load plugins stop at **optimize images**. Smart LazyLoad also defers responsive `<picture>` sources, inline background images, avatars, smilies, HTML5 `<video>`, and iframes such as YouTube and Vimeo.

This plugin also includes support for **avatars, emojis, native video, native browser lazy loading, and thumbnail placeholders**, as well as the ability to convert YouTube videos.

There is nothing to configure to get started — images are lazy loaded the moment you activate it. 🚀

You get two layers of control:

* A **Master Switch** for the whole site.
* A **per-post override**, so a single post or page can behave differently from everything else.

The rest lives on one settings screen: choose what to lazy load, tune performance, decide how placeholders look, and exclude anything that shouldn't be touched.

= 📦 What gets lazy loaded? =

* **Images** — post and page content, featured images, widget images, and comments. Switch on Full-Page Lazy Loading and it also covers markup hardcoded in your theme's templates.
* **Responsive `<picture>` sources** — every `<source>` inside a `<picture>` is deferred together with its fallback `<img>`. The browser still picks the format and crop it wants; only the timing changes.
* **Avatars** — Gravatars and author photos, which usually sit far below the fold in long comment threads.
* **Smilies** — text smilies (e.g. `:mrgreen:`) that WordPress renders as image files. Smilies rendered as Unicode emoji are left untouched.
* **Background images** — an inline `style="background-image"` built from a single `url()`, or a manual `data-bg` attribute. Gradients, `image-set()`, and multi-layer backgrounds are deliberately left untouched.
* **Iframes** — any embedded iframe, including YouTube and Vimeo players.
* **YouTube click-to-play thumbnails** — an optional mode that swaps the YouTube iframe for a light, clickable thumbnail until someone actually wants to watch. Thumbnails are served as WebP, with an automatic fallback.
* **Native `<video>`** — HTML5 `<video>` tags, their `<source>` children, and `poster` images.

= 🎛️ Two layers of on/off control =

* A **Master Switch** turns the whole plugin on or off for the site
* Switch it off and every other setting is dimmed, so nothing gets changed by mistake. Nothing is cleared either — turn it back on and your configuration is exactly as you left it
* A **Lazy Load** dropdown in the post editor sidebar — **Default**, **Enable**, or **Disable** — lets one post override the site-wide setting, leaving every other post alone

= ⚡ Performance tuning =

* Skips the first image on the page, and any image WordPress marks as your largest above-the-fold image, to protect your Largest Contentful Paint (LCP)
* Excluded elements also lose WordPress's own `loading="lazy"`, so they really do load straight away
* Adjustable distance-from-viewport threshold, so loading starts as early or as late as you like
* Use the plugin's IntersectionObserver engine, or hand the job to the browser's native `loading="lazy"`
* Scan the whole page, or only post content, widgets, and comments — full coverage or the lightest possible footprint
* Always loads its script in the footer, with an optional `defer` on top, so it never blocks rendering
* Can be turned off for logged-in users, so you always see full-quality content while editing

= 🎨 Appearance while content loads =

* Low-quality image placeholder (LQIP): a tiny blurred preview of the real image instead of a blank box
* Previews are built in the background and cached, so no visitor ever waits for one
* Pick which registered image size the preview is built from
* Adjustable fade-in for the moment content arrives, skipped for visitors who prefer reduced motion
* Every deferred image holds its exact final size from the first paint, so nothing jumps when it arrives
* Optional placeholder background colour, shown only until the real image is there

= 🧩 Compatibility and control =

* A custom exclude field — list your own CSS classes, one per line or separated by commas. No code needed
* Recognises the usual exclusion markers already: `no-lazyload`, `skip-lazy`, `data-no-lazyload`, `data-no-lazy`, `data-skip-lazy`
* Stays out of the way inside page builder editors (Elementor, Avada, Divi, Beaver Builder, WPBakery, Oxygen) and on feeds, previews, and REST requests
* Developer filters for placeholders, threshold, exclusions, YouTube thumbnails, and the final markup
* WP-CLI commands to build or clear image previews across the whole media library
* One-click "Reset to Defaults" whenever you want to start over

= 🛠️ Built the right way =

* No jQuery. The frontend script is plain JavaScript built on IntersectionObserver
* `noscript` fallbacks, so content is never lost for visitors or crawlers without JavaScript
* A responsive, card-based settings screen
* Clean uninstall: removes its own options and post meta when you delete the plugin, and nothing else

== Screenshots ==

1. Smart LazyLoad settings menu in the WordPress admin.
2. Main settings to enable lazy loading and choose what to optimize.
3. Performance settings for Core Web Vitals and loading behavior.
4. Appearance settings for image previews, colors, and the fade-in.
5. Advanced settings for exclusions and compatibility options.
6. Per-post override settings in the WordPress editor.

== Installation ==

= From your WordPress dashboard =

1. Navigate to **Plugins → Add New Plugin**
2. Search for **Smart LazyLoad**
3. Click **Install Now**, then **Activate**
4. Go to **Settings → LazyLoad** to review the defaults — lazy loading for images is already on out of the box

= Manual upload =

1. Download the plugin's ZIP file
2. Upload the `lazy-load-for-images` folder to `/wp-content/plugins/`
3. Activate the plugin from **Plugins → Installed Plugins**
4. Visit **Settings → LazyLoad** to adjust anything, or leave the defaults as they are

No further setup is required — lazy loading starts working on the frontend as soon as the plugin is active.

== Configuration ==

= Site-wide settings: Settings → LazyLoad =

The settings screen is organized into five cards:

**Master Switch** — the single toggle that turns Smart LazyLoad on or off for the entire site. When it's off, every card below it is dimmed and cannot be edited, but nothing about your saved configuration changes.

**What to Lazy Load** — a separate toggle for each type: Images, Responsive `<picture>` Sources, Background Images, Avatars, Smilies, Iframes, YouTube Thumbnail Replacement, and Native Videos.

**Performance** — Skip First Image (for LCP), Threshold Distance, Use Native Browser Lazy Loading, Defer LazyLoad JavaScript, and Disable for Logged-in Users.

**Appearance** — Low-Quality Image Placeholder and its source size, an optional Placeholder Background Colour, and the Fade-in Duration.

**Advanced** — Full-Page Lazy Loading, and a Custom Exclude Selectors box where you list CSS classes to skip — one per line, or separated by commas.

A **Reset to Defaults** button at the bottom restores every option to its original value in one click.

= Per-post override =

Open any post, page, or public custom post type in the block editor and look for the **Smart LazyLoad** panel in the sidebar. Its **Lazy Load** dropdown has three choices:

* **Default (On)** or **Default (Off)** — label reflects the current Master Switch state; this post simply follows the site-wide setting
* **Enable** — lazy loading is always on for this post, even if the Master Switch is off
* **Disable** — lazy loading is always off for this post, even if the Master Switch is on

The choice is saved as post meta and applies only to that single post — nothing else on the site is affected.

= Developer filters =

Every filter is prefixed `smart_lazyload_`.

`smart_lazyload_enabled` — return `false` to disable lazy loading for the current request.

`smart_lazyload_svg_placeholder` — replace the default inline SVG placeholder used for images.

`smart_lazyload_placeholder` — replace the placeholder value used for deferred iframes (default: `about:blank`).

`smart_lazyload_excluded_attributes` — extend the list of strings that exclude an image, video, or background-image tag from lazy loading.

`smart_lazyload_iframe_excluded_patterns` — extend the list of strings that exclude an iframe tag from lazy loading.

`smart_lazyload_excluded_src` — extend the list of substrings checked against an image or background-image URL itself (not just its surrounding tag) to exclude it from lazy loading; useful for dynamic image generators or known placeholder assets.

`smart_lazyload_threshold` — override the distance-from-viewport threshold, in pixels.

`smart_lazyload_youtube_resolution` — choose the YouTube thumbnail resolution: `default`, `mqdefault`, `hqdefault` (the default), `sddefault`, or `maxresdefault`.

`smart_lazyload_exclude_youtube_thumbnail` — return an array of strings; any YouTube iframe whose markup contains one of them keeps a real iframe instead of the click-to-play player.

`smart_lazyload_html` — filter the processed markup after every lazy-load pass has run.

The former `do_smart_lazyload` and `smll_threshold` names still work, so existing snippets keep running.

== Frequently Asked Questions ==

= What exactly does Smart LazyLoad defer? =

Images in post and page content, featured images, widget images, comments, avatars, and smilies, plus `<picture>` sources, inline background images, iframes (YouTube, Vimeo, and others), and native `<video>` elements. Turn on Full-Page Lazy Loading and anything your theme's templates output directly is covered too. Each content type has its own on/off toggle, so you decide what applies.

= How is this different from a plugin that only lazy loads images? =

Most lazy load plugins stop at `<img>` tags. Smart LazyLoad also handles background images, `<picture>` responsive sources, videos, and iframes, and adds a second layer of control on top of the usual site-wide switch: a per-post override that lets a single page behave differently from the rest of the site.

= Does this work with AMP pages? =

Yes, safely: on any page served through the AMP plugin, Smart LazyLoad detects the AMP endpoint and skips lazy loading entirely — including its scripts and styles — since AMP's markup rules don't allow the attributes lazy loading needs. Non-AMP pages are unaffected.

= How do I make one specific post behave differently from the rest of the site? =

Open that post or page in the editor and find the **Smart LazyLoad** panel in the sidebar. Set the **Lazy Load** dropdown to **Enable** to force lazy loading on for that post only, or **Disable** to force it off — either way, every other post keeps following the site-wide Master Switch untouched.

= If I turn the Master Switch off, do I lose my other settings? =

No. Every other option on the settings page is dimmed and can't be edited while the Master Switch is off, but its saved value is untouched. Turn the Master Switch back on and your previous configuration is exactly as you left it.

= How do I exclude one image, video, or iframe from being lazy loaded? =

Add any of these to the element: `no-lazyload`, `skip-lazy`, `data-no-lazyload`, `data-no-lazy`, or `data-skip-lazy`.

An element already marked `loading="eager"` or `fetchpriority="high"` is left alone too, so the hints you use for your LCP image keep working.

For your own CSS classes, list them under **Settings → LazyLoad → Custom Exclude Selectors** — one per line, or separated by commas. The leading dot is optional, so `.site-logo` and `site-logo` both work.

A class only counts when it matches in full, so `.hero` never accidentally excludes `hero-thumbnail`.

= Can I disable lazy loading with code instead of the settings page? =

Yes.

`
add_filter( 'smart_lazyload_enabled', '__return_false' );
`

Or conditionally, for example only on single posts:

`
add_action( 'wp', function () {
	if ( is_single() ) {
		add_filter( 'smart_lazyload_enabled', '__return_false' );
	}
} );
`

= Does it support background images? =

Yes, in two ways. Automatically, for any element carrying an inline background:

`
<div style="background-image:url(photo.jpg)"></div>
`

Or manually, by writing the plugin's own markup yourself:

`
<div class="smart-background" data-bg="photo.jpg"></div>
`

Use a plain URL in `data-bg` — no `url(...)` wrapper and no quotes.

Either way the background is restored automatically for visitors with JavaScript turned off.

Only a background made of one plain `url()` is deferred. Gradients, `image-set()`, and multi-layer backgrounds are left exactly as you wrote them, so a value that can't be rebuilt safely is never taken apart.

= Does it support responsive `<picture>` markup? =

Yes. Every `<source>` inside a `<picture>` element has its `srcset`/`sizes` deferred in sync with the fallback `<img>`. The browser still decides which source to use based on format and viewport — Smart LazyLoad only changes *when* the chosen source loads.

= Will lazy loading make my layout jump around? =

No. A deferred image is held open by a placeholder cut to that image's exact `width` and `height`, so the space is reserved from the first paint and nothing moves when the real image arrives.

= Which method should I use: Full-Page or content only? =

Both are safe; they differ in reach. Leave **Full-Page Lazy Loading** off and the plugin only touches post content, widgets, comments, and avatars — the lightest possible option, and enough for most sites. Turn it on and the whole response is scanned, so images your theme prints directly in its templates (sliders, headers, footers) are covered too. Only one of the two runs at a time, so nothing is ever processed twice.

= What is the low-quality image placeholder (LQIP)? =

Instead of an empty box, Smart LazyLoad shows a tiny blurred preview of the real image while the full version loads. Previews are built in the background, never during a visitor's page load, and cached from then on. Choose the source size under **Settings → LazyLoad → Placeholder Source Size**.

On a large existing media library you can build every preview up front from the command line:

`
wp smart-lazyload generate-lqip
`

Add `--force` to rebuild previews that already exist, or `--limit=100` to work through the library in batches. To remove every stored preview:

`
wp smart-lazyload clear-lqip
`

= Can an image ever get stuck invisible while fading in? =

No. The fade only ever runs on an element that has already arrived, so an image that fails to load, or a visitor whose JavaScript never runs, simply sees it at full opacity.

= Can I use my own placeholder image instead of the built-in SVG? =

Yes.

`
add_filter( 'smart_lazyload_svg_placeholder', function () {
	return 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"></svg>';
} );
`

Deferred iframes use a separate placeholder (default `about:blank`), which you can change with:

`
add_filter( 'smart_lazyload_placeholder', function () {
	return 'about:blank';
} );
`

= Will this conflict with my caching, CDN, or other performance plugins? =

No. Smart LazyLoad only changes the HTML markup for images, videos, and iframes on the fly; it doesn't touch how pages are cached or served, so it works alongside typical caching and CDN setups.

= Is Smart LazyLoad SEO-friendly? =

Yes. Deferred content is always wrapped with a working `<noscript>` fallback, native browser lazy loading is supported directly, and the first image on the page is skipped by default so it doesn't hurt your Largest Contentful Paint score.

= Lazy loading doesn't seem to be working. What should I check? =

* Confirm the Master Switch is on, and that the specific post isn't set to **Disable** in its Lazy Load panel
* Clear any page cache, CDN cache, or browser cache
* Check whether "Disable for Logged-in Users" is on and you're viewing the page while logged in
* Temporarily disable other lazy load plugins to rule out a conflict
* Make sure the element doesn't carry one of the exclusion classes/attributes
* View the actual frontend page, not a page-builder editing screen or preview

== Upgrade Notice ==

= 3.0.0 =
Major update with improved lazy loading, WebP YouTube thumbnails, better exclusions, AJAX support, and numerous fixes.

== Changelog ==

= 3.0.0 =

* Added: WebP YouTube thumbnails with automatic fallback.
* Added: filters for markup, thumbnail resolution, and click-to-play.
* Added: Defer LazyLoad JavaScript; the script now always loads in the footer.
* Improved: conditional assets, unified observer, fade-in, and reduced-motion support.
* Improved: unified `smart_lazyload_` developer filter prefix; older names still work.
* Improved: unavailable settings are now clearly dimmed.
* Fixed: excluded, above-the-fold, broken, and responsive images load correctly.
* Fixed: backgrounds, videos, iframes, and `<picture>` sources handle edge cases correctly.
* Fixed: complex background URLs, AJAX content, YouTube links, and nocookie embeds.
* Fixed: class exclusions, image previews, placeholders, and long image attributes.
* Fixed: lazy-load classes, video handling, and cleanup on deactivation/uninstall.

= 2.9.5 =

* Fixed: native lazy loading didn't work on iframes.
* Fixed: "Skip First Image" could pick the wrong image.
* Fixed: the exclude list ignored entries written as `.class`.
* Fixed: smiley images could misbehave on feeds.
* Improved: placeholders now match the image size, so pages don't jump.
* Improved: placeholders are built in the background, never during a page load.

= 2.9.4 =

* Added: separate toggle for Gravatar/avatar images.
* Added: optional Full-Page Mode to also lazy load images hardcoded in the theme.

= 2.9.3 =

* Fixed: iframes (Vimeo, Google Maps, embeds) now lazy load properly.
* Fixed: more YouTube link formats are detected.
* Improved: better detection of page builder editors.
* Added: smiley images now lazy load too.

= 2.9.0 =

* Improved: images and picture tags are now detected in any HTML format.

= 2.8.0 =

* Added: AMP pages are skipped automatically.

= 2.7.0 =

* Fixed: script/noscript content no longer gets corrupted.
* Added: exclude list for known placeholder images.

= 2.6.0 =

* Added: retina background images, and a WP-CLI command to pre-generate placeholders.
* Fixed: YouTube button label wasn't translatable.

= 2.5.0 =

* Changed: YouTube play button icon now loads from the plugin, not YouTube.
* Changed: background images use their own CSS class now.

= 2.4.1 =

* Added: per-post Enable/Disable option in the editor sidebar.
* Fixed: first save after install could turn on every setting by mistake.
* Fixed: a stray double space in background-image markup.

= 2.4.0 =

* Fixed: a JavaScript error on some pages.
* Fixed: background images that never finished fading in.
* Fixed: picture tags loading inconsistently.
* Changed: settings page redesigned.

= 2.3.0 =

* Fixed: class name mismatches that broke lazy loading and fade-in.
* Fixed: settings not saving correctly.
* Fixed: a bug that could crash the background-image handler.
* Added: option to load the script in the footer.

= 2.2.0 =

* Added: picture tag support.
* Added: low-quality image placeholder option.

= 2.1.0 =

* Added: video lazy loading.
* Added: fade duration, placeholder color, and exclude list settings.
* Added: Reset to Defaults button.

= 2.0.2 =

* Fixed: saving settings could reset the threshold value.

= 2.0.1 =

* Added: settings are removed cleanly on uninstall.
* Verified with WordPress 7.0.2 and PHP 8.

= 2.0.0 =

* Rewrite: added video, iframe, and background-image lazy loading.
* Added: YouTube thumbnail mode.
* Changed: settings page rebuilt.