Which loading engine should I choose?
Smart uses the JavaScript engine for viewport-based loading and the plugin’s loading controls. Hybrid uses native loading for supported images and iframes, with JavaScript handling other eligible media. Native leaves image and iframe loading to the browser without loading the main lazy-loading library.
Native mode does not defer background images. For HTML5 videos, it adds preload="none" when no preload value is set, rather than deferring sources and posters. Optional YouTube thumbnail replacement uses a separate click-to-play script. Thresholds and JavaScript loading effects do not control native browser loading.
How do I keep important images from being delayed?
Open the Performance tab and enable Protect Important Images . Choose the first image, first two images, or a custom count. In content-only mode, the count applies separately to each processed content fragment; in full-page mode, it applies to the page response.
For a specific image, use loading="eager" , fetchpriority="high" , or an exclusion marker. Check your page’s actual LCP image rather than relying on its position alone.
How do I exclude an element or media URL?
In General → Exclusions , enter classes such as .site-logo or IDs such as #hero-image under Exclude with Classes & IDs . These are individual class or ID matches, not complex CSS selectors. Source URL exclusions match plain substrings of media URLs, not page URLs or regular expressions.
You can also add the skip-lazy class or a data-skip-lazy attribute directly to an image, video, iframe, or supported background element. Other recognized markers include no-lazyload , data-no-lazyload , and data-no-lazy .
Example: <img src="logo.png" alt="Site logo" class="skip-lazy">
Can I disable processing on selected pages?
Use General → Page Type Exclusions to skip the front page, blog index, archives, or search results. For an individual post, page, or supported public custom post type, use the Smart LazyLoad editor panel:
- Default: follow the site-wide settings.
- Enable: allow processing for this entry, including when its page type is excluded.
- Disable: skip processing for this entry.
The master switch must remain on. A per-post Enable selection does not bypass the master switch or request-level exclusions, such as AMP protection or disabling processing for logged-in users. Turning off the master switch preserves your saved configuration.
What does Full-Page Lazy Loading change?
By default, the plugin processes supported WordPress content fragments, such as post content, widgets, featured images, and comments. Enable Full-Page Lazy Loading in Advanced to process the complete HTML response, including eligible media printed directly by theme templates. Only one processing approach runs at a time.
How are background images handled?
Enable Background Images in the Content tab to process inline declarations such as <div style="background-image:url(photo.jpg)"></div> . Backgrounds declared only in external stylesheets are not detected automatically.
For manual markup, use <div class="smart-background" data-bg="photo.jpg"></div> . The data-bg value can be a plain image URL. Enable the background variants option for supported retina attributes, multi-layer expressions, and image-set() backgrounds. Gradient-only backgrounds are left unchanged.
Background processing requires Smart or Hybrid mode. The plugin adds fallback CSS for processed backgrounds when JavaScript is disabled.
What are low-quality image placeholders?
A low-quality image placeholder (LQIP) is a small preview shown while the full image loads. Select it in Appearance and choose a registered image size as its source. Previews for eligible media-library images are generated in the background and cached; an unavailable preview uses the standard placeholder instead.
To prepare previews with WP-CLI, run wp smart-lazyload generate-lqip . Use --force to rebuild existing previews or --limit=100 to restrict the command to the first 100 matching attachments. The limit is not a pagination or resumable-batch option. Run wp smart-lazyload clear-lqip to remove cached previews.
Does it work with page builders and AMP?
Page-builder editor protection and AMP exclusions are enabled by default. The plugin detects supported editing contexts, including Elementor, Avada, Divi, Beaver Builder, WPBakery, and Oxygen, and skips processing there. AMP pages detected through the AMP plugin are also skipped. These controls are available in Advanced .
Feeds, previews, admin screens, and REST requests are not processed. Review the published frontend page when testing lazy loading.
Can I use it with caching, a CDN, or another lazy-loading plugin?
Smart LazyLoad rewrites eligible frontend markup without modifying the original media files. Test it with your theme and caching or CDN setup, and clear cached pages after changing settings.
Avoid running multiple lazy-loading systems on the same media. The Advanced tab includes optional controls to disable WordPress core lazy loading for managed media and Jetpack Lazy Images processing. Enable these only when needed; the Jetpack option does not disable its image CDN.
What happens when JavaScript is disabled?
JavaScript-deferred images, iframes, and videos include <noscript> fallbacks. Processed backgrounds use fallback CSS. Native mode keeps the media sources available and relies on the browser’s loading behavior.
How can developers customize the plugin?
Use smart_lazyload_enabled to control processing for a request. For example, add_filter( 'smart_lazyload_enabled', '__return_false' ); disables it. Defining DONOTLAZYLOAD as true also skips processing for the request.
Available filters include:
- smart_lazyload_svg_placeholder — image placeholder value.
- smart_lazyload_placeholder — deferred iframe placeholder, normally about:blank .
- smart_lazyload_threshold — JavaScript loading distance in pixels.
- smart_lazyload_excluded_attributes — exclusion strings for image, video, and background markup.
- smart_lazyload_iframe_excluded_patterns — iframe markup exclusions.
- smart_lazyload_excluded_src — media source URL exclusions.
- smart_lazyload_youtube_resolution — thumbnail resolution; the default is hqdefault .
- smart_lazyload_exclude_youtube_thumbnail — YouTube embeds that should keep their iframe instead of a thumbnail.
- smart_lazyload_html — processed content output.
- smart_lazyload_iframe_html — individual JavaScript-deferred iframe output.
- smart_lazyload_youtube_html — YouTube thumbnail player output.
- smart_lazyload_bg_images_regex — single-URL inline background matching expression.
The legacy do_smart_lazyload and smll_threshold filters remain supported. The settings screen’s User Guide tab includes usage examples.
Why is an image or embed not being lazy loaded?
Check that the master switch and relevant content option are enabled. Then check the post override, important-image protection, element and URL exclusions, and page-type settings. If logged-in users are excluded, test in a logged-out browser session.
Clear page and browser caches, test the published frontend, and temporarily disable competing lazy-loading features. Media already marked up by another lazy-loading system may be left untouched. In native mode, the browser decides how early offscreen resources load.
Are settings removed when I uninstall the plugin?
Not by default. Enable Advanced → Delete Data on Uninstall to remove the plugin’s settings, per-post overrides, and stored image previews when it is deleted. Otherwise, those settings remain available for a later reinstall. Deactivation does not remove your configuration.
