View Categories

Optimization Exclusion Attributes

3 min read

These HTML attributes control FastPixel optimization for individual elements or whole sections of a page. Add them to the original page or template before optimization, then purge and regenerate the FastPixel cache of the affected pages.

To exclude whole pages, URL parameters, or JavaScript and CSS files instead, see FastPixel – Exclusions.

Reference #

AttributeScopeEffect
data-no-optimizeElement and descendantsSkips selector-based optimization, including image rewriting, and the general media lazy-loading rewrite.
data-fastpixel-ignoreElement and descendantsAlias for the exclusion behavior of data-no-optimize.
data-no-lazyimgImage or ancestorFor valid raster images, skips image lazy placeholders and FastPixel responsive source generation. Image CDN rewriting remains enabled.
data-no-lazybgBackground element or ancestorDisables background-image lazy loading. Background-image optimization and CDN rewriting remain enabled.

Attributes are checked by presence, not by their value. For example, data-no-optimize="false" still excludes an element. Use an empty attribute to avoid ambiguity.

Exclude an image from rewriting #

Use data-no-optimize directly on the image:

<img id="logo" src="/images/logo.webp" alt="Site name" data-no-optimize>

Alternatively, put it on an existing wrapper to cover all images inside it:

<div class="logo_container" data-no-optimize>
    <a href="/">
        <img id="logo" src="/images/logo.webp" alt="Site name">
    </a>
</div>

data-fastpixel-ignore can be used in place of data-no-optimize. There is no need to add data-no-lazyimg alongside either broad exclusion.

For themes that clone or swap logos, an existing persistent wrapper can cover replacement images as well, provided they remain inside that wrapper during optimization.

Disable image lazy loading only #

<img src="/images/logo.webp" alt="Site name" data-no-lazyimg>

For valid raster images, FastPixel outputs a normal image src instead of its lazy-loading placeholder and list of responsive sources. The URL can still be rewritten to the image CDN. This is not a full image optimization exclusion, and it does not guarantee that an image which fails to load during optimization is preserved.

The attribute can also be placed on a wrapper to apply to the images inside it.

Disable background lazy loading only #

<section data-no-lazybg style="background-image: url('/images/banner.webp')">
    <h1>Page title</h1>
</section>

The background remains eligible for optimization and CDN rewriting, but FastPixel does not defer it with its background lazy-loading marker. The attribute also applies to background elements inside it.

Limits and cache refresh #

  • Add the attributes in the source markup, not with JavaScript after optimization.
  • Adding an attribute to already-optimized HTML does not undo existing rewrites or restore an image URL that has already become a blank placeholder.
  • After changing the source markup, purge and regenerate every affected page and any relevant cached variant (for example, the mobile cache). With WP-CLI, you can purge a page with wp fastpixel purge <url>.
  • Broad exclusions are not an isolation boundary: shared CSS and theme or plugin JavaScript can still affect the excluded elements.
  • The image and background lazy-loading attributes do not disable native browser lazy loading or lazy loading added by another plugin.
  • The data-fpo-* attributes you may see in optimized HTML are FastPixel output, not substitutes for these source-level controls.
en_USEnglish