LCP Optimization – Powered Cache Documentation

This feature is available in Powered Cache Premium and is designed to help the browser get your above-the-fold content on screen faster by:

Detecting the Largest Contentful Paint (LCP) image
Preloading that image with proper hints
Optionally preloading critical fonts
Coordinating with Critical CSS to prioritize key styles

It works automatically on compatible front-end page loads once enabled in your Powered Cache settings.

How LCP Optimization works

Internally, the feature runs as an output buffer on front-end HTML requests and makes three passes over the generated HTML:

Preload the LCP image
Preload critical fonts (optional, via filter)
Prioritize Critical CSS (when Critical CSS is enabled)

It does not run:

In the WordPress dashboard (is_admin())
On REST API requests
On trackbacks, robots, or preview pages
On non-GET requests

Developers can also programmatically skip it using powered_cache_skip_lcp_optimization filter.

1. LCP image detection and preloading

How the LCP image is detected

The feature parses the final HTML and uses a few heuristics to guess the most likely LCP candidate:

<picture> elements (highest priority)
It looks for the first <picture> in common content areas:
- //main//picture[1]
- //article//picture[1]
- first <section> and then top-level <picture>
If an <img> is inside that <picture>, its URL, srcset, and sizes are used.
Hero / main content images If no <picture> is found, it checks for the first <img> in:
- <main>
- <article>
- containers with hero or banner in the class name
- the first <section>
- finally, the first <img> in <body>
Images inside <picture> elements are skipped here because they are already handled in step 1.
Video posters If a <video> tag has a poster attribute, that poster can be used as an LCP candidate.

Once a candidate is found, the plugin extracts:

url (image URL)
srcset (if present)
sizes (if present)
type (MIME type based on the file extension: jpeg, png, webp, avif, svg, etc.)

Developers can override or completely disable the detection result via the powered_cache_lcp_image filter.

Preloading the LCP image

If an LCP candidate is found and not already preloaded, Powered Cache Premium injects a <link> tag into the <head>:

<!-- LCP Optimization: Image Preload by Powered Cache Premium -->
<link
  rel="preload"
  as="image"
  href="https://example.com/path/to/image.jpg"
  imagesrcset="..."
  imagesizes="..."
  type="image/jpeg"
  fetchpriority="high">

Key points:

It checks existing <link rel="preload"> or <link rel="prefetch"> tags to avoid duplicates.
fetchpriority="high" is added to further hint that this image is critical.
If srcset or sizes are available, they are passed as imagesrcset and imagesizes attributes.

You can adjust the attributes via the powered_cache_lcp_preload_attributes filter.

2. External domains and preconnect hints

If the detected LCP image (or any image in its srcset) is served from an external domain (for example, a CDN), that domain is tracked internally.

Later, Powered Cache Premium adds preconnect hints for these domains through the standard wp_resource_hints filter:

add_filter( 'wp_resource_hints', [ $lcp, 'add_resource_hints' ], 10, 2 );

For relation type preconnect:

Detected external origins used by LCP-critical images and fonts are added.
Developers can add their own origins via the powered_cache_lcp_preconnect_domains filter.
Duplicates are removed before output.

This helps the browser open connections early to important external hosts.

3. Critical font preloading (optional)

Font preloading is disabled by default and controlled entirely by a filter.

Enabling font preloading

Developers can enable font preloading with:

add_filter( 'powered_cache_enable_lcp_font_preload', '__return_true' );

How font preloading works

When enabled:

The HTML is scanned for inline <style> blocks.
Inside those styles, the plugin looks for @font-face declarations.
It extracts url(...) values and optional format(...) descriptors.
It determines a MIME type from the format or file extension.
Only modern formats are considered for preloading:
- font/woff2
- font/woff
The number of fonts to preload is capped (default: 2) and can be changed via: add_filter( 'powered_cache_lcp_max_fonts_to_preload', function () { return 3; // for example } );

For each selected font, a preload tag like this is injected into the <head>:

<!-- LCP Optimization: Font Preload by Powered Cache Premium -->
<link
  rel="preload"
  as="font"
  href="https://example.com/fonts/myfont.woff2"
  type="font/woff2"
  crossorigin="anonymous">

You can modify attributes with the powered_cache_lcp_font_preload_attributes filter, and you can adjust or fully override the font list with powered_cache_lcp_font_urls.

External font hosts (for example, a font CDN) are also added to the preconnect list.

4. Critical CSS prioritization

The LCP Optimization feature also coordinates with Critical CSS, when it is enabled in Powered Cache settings.

Requirements

critical_css must be enabled in the plugin settings.
LCP CSS optimization is on by default, but controlled by a filter.

To control it:

// Disable LCP CSS optimization
add_filter( 'powered_cache_enable_lcp_css_optimization', '__return_false' );

What it does

When active:

The plugin looks only at the <head> part of the HTML for performance reasons.
It searches for <link> tags that match one or more patterns supplied by the
powered_cache_lcp_priority_css_patterns filter. By default, it includes: 'wp-content\/themes\/[^\/]+\/style\.css' // Main theme style.css
For matching <link> tags that do not already have a fetchpriority attribute, it rewrites them as:  <link rel="stylesheet" href="..." fetchpriority="high">

This hints to the browser that those stylesheets are especially important for rendering.

Developers can expand or change which CSS files are treated as high priority by adjusting the regex patterns passed to powered_cache_lcp_priority_css_patterns.

When LCP Optimization runs (and when it does not)

LCP Optimization processing is only started when:

The internal setting enable_lcp_optimization is truthy, or
A developer explicitly enables it via the powered_cache_enable_lcp_optimization filter.

Additionally, it runs only when:

Request method is GET
It is not a REST API request
It is not is_admin(), is_trackback(), is_robots(), or is_preview()
The output looks like HTML (contains <html or <!doctype)

If any of those conditions are not met, the HTML output is returned untouched.

Skipping LCP Optimization for specific pages

You may want to disable LCP Optimization under certain conditions, for example:

On specific URLs
For logged-in users
For particular post types

You can do that via the powered_cache_skip_lcp_optimization filter:

add_filter( 'powered_cache_skip_lcp_optimization', function ( $skip ) {
    if ( is_user_logged_in() ) {
        return true;
    }

    if ( is_page( 'my-custom-page' ) ) {
        return true;
    }

    return $skip;
} );

Returning true skips the entire LCP Optimization process for that request.

Developer filters and hooks

Here is a summary of the main hooks available for customization.

Enable or disable the feature globally

/**
 * Enable or disable LCP optimization (overrides settings)
 */
add_filter( 'powered_cache_enable_lcp_optimization', function ( $enabled ) {
    return true; // force enable, for example
} );

Skip LCP optimization for certain requests

add_filter( 'powered_cache_skip_lcp_optimization', function ( $skip ) {
    // Your conditions here
    return $skip;
} );

Override detected LCP image

add_filter( 'powered_cache_lcp_image', function ( $lcp_image, $html ) {
    // Example: force a specific hero image on the front page
    if ( is_front_page() ) {
        return [
            'url'    => 'https://example.com/path/to/hero.webp',
            'srcset' => '',
            'sizes'  => '',
            'type'   => 'image/webp',
        ];
    }

    return $lcp_image;
}, 10, 2 );

Customize LCP image preload attributes

add_filter( 'powered_cache_lcp_preload_attributes', function ( $attributes, $lcp_data ) {
    // Add or change attributes if needed
    // $attributes['media'] = '(min-width: 768px)';
    return $attributes;
}, 10, 2 );

Add extra preconnect domains

add_filter( 'powered_cache_lcp_preconnect_domains', function ( $domains ) {
    $domains[] = 'https://cdn.example.com';
    return $domains;
} );

Enable font preloading

add_filter( 'powered_cache_enable_lcp_font_preload', '__return_true' );

Adjust font list or limit

// Change max number of fonts to preload
add_filter( 'powered_cache_lcp_max_fonts_to_preload', function () {
    return 3;
} );

// Inspect or adjust detected fonts
add_filter( 'powered_cache_lcp_font_urls', function ( $fonts, $html ) {
    // $fonts is an array of [ 'url' => ..., 'type' => ... ]
    return $fonts;
}, 10, 2 );

Customize font preload attributes

add_filter( 'powered_cache_lcp_font_preload_attributes', function ( $attributes, $font_data ) {
    // Example: change crossorigin mode
    // $attributes['crossorigin'] = 'use-credentials';
    return $attributes;
}, 10, 2 );

Control which CSS files get `fetchpriority="high"`

add_filter( 'powered_cache_lcp_priority_css_patterns', function ( $patterns ) {
    // Add your own patterns (regex without delimiters)
    $patterns[] = 'wp-content\/plugins\/my-builder\/assets\/css\/frontend\.css';
    return $patterns;
} );

Notes and best practices

LCP Optimization is an advanced feature intended to complement your existing caching and optimization setup.
It relies on output buffering and HTML parsing, so it is most suitable for standard front-end page responses.
When combining it with other optimization plugins or custom output filters, it is a good idea to test key templates (home, blog, product pages, etc.) to ensure everything renders as expected.

You can now wire this up in your docs site (for example under a “Premium Features → Automatic LCP Optimization” section) and trim or expand the developer examples depending on how deep you want the public documentation to go.

How LCP Optimization works

1. LCP image detection and preloading

How the LCP image is detected

Preloading the LCP image

2. External domains and preconnect hints

3. Critical font preloading (optional)

Enabling font preloading

How font preloading works

4. Critical CSS prioritization

Requirements

What it does

When LCP Optimization runs (and when it does not)

Skipping LCP Optimization for specific pages

Developer filters and hooks

Enable or disable the feature globally

Skip LCP optimization for certain requests

Override detected LCP image

Customize LCP image preload attributes

Add extra preconnect domains

Enable font preloading

Adjust font list or limit

Customize font preload attributes

Control which CSS files get fetchpriority="high"

Notes and best practices

Related Articles

Prefetch Links

Preconnect Resources

Prefetch DNS

Enable Sitemap Preloading

Enable Cache Preloading

Control which CSS files get `fetchpriority="high"`