Kadence Blocks

Kadence Blocks is built around several core functional pillars:

• Intelligent Load: Only loads necessary CSS or JavaScript for the specific blocks used on a page to maintain performance.
• Responsive Controls: Allows tweaking design settings (padding, margins, typography) specifically for desktop, tablet, and mobile views.
• Design Library: Provides hundreds of pre-built patterns and pages to accelerate site assembly.
• Typography & Color: Access to 900+ Google fonts, gradients, overlays, and parallax backgrounds.
• Configurable Defaults: Define default settings for blocks to ensure consistency across a site.
• Setting Visibility Controls: Ability to hide specific block settings from certain user roles.

The Optimizer improves Core Web Vitals (LCP, CLS, INP) using a two-phase process:

1. Analysis Phase (Client-side): When optimization is triggered in wp-admin, JavaScript (via @stellarwp/perf-analyzer-client) analyzes the page to detect critical images, section heights, and optimal image sizes for desktop and mobile viewports.
2. Application Phase (Server-side): On subsequent requests, the stored analysis data is used to apply optimizations such as proper lazy loading, content-visibility: auto for below-the-fold sections, and optimal image sizes attributes.

Hash-Based Invalidation: To ensure optimizations remain accurate, the system compares HTML hashes on each request. If the HTML hash differs from the stored hash for a specific viewport, the data is marked isStale = true and re-optimization is required.

You can manually trigger the storage of HTML hashes for specific viewports by appending query parameters to the URL. This is useful for forcing a re-analysis of the page content.

?kadence_set_optimizer_hash=1           # Desktop hash
?kadence_set_optimizer_hash=1&kadence_is_mobile=1  # Mobile hash

The Optimizer can be enabled globally through the Gutenberg editor interface:

1. Open a post or page in the block editor.
2. Click the Kadence "K" icon in the top toolbar to open Kadence Blocks Controls.
3. Expand the Performance Optimizer panel.
4. Toggle "Globally Enable The Performance Optimizer".

This setting is stored in the kadence_blocks_settings option under the key performance_optimizer_enabled.

Upgrading to the Pro version unlocks advanced features including:

• Advanced Blocks: Advanced Query Loop, Advanced Slider, Image Overlay, Modal, Post Grid/Carousel, Product Carousel, Repeater, and Split Content.
• Premium Functionality: Animate on Scroll, Custom Icons, Custom Fonts, Dynamic Content (integrating with ACF, MetaBox, WooCommerce, etc.), and Page Specific Scripts.
• Expanded Design Library: Access to over 800+ additional patterns.

The KadenceBlocksHome component consumes a global configuration object named kadenceHomeParams (attached to the window object). This object controls the dashboard's logic and visibility.

Available Properties

• isAuthorized: Boolean indicating if the user is authenticated for AI features.
• isNetworkAdmin: Boolean indicating if the user has network-level administrative privileges.
• isNetworkEnabled: Boolean indicating if the network features are enabled.
• pro: String 'true' or other values indicating if the user has a Pro license.
• homeContent: An object containing configuration for actionCards and knowledgeBase.
• disconnectUrl: The URL used to revoke AI access.

Logic for showControls

Controls are shown if:

• The user is a Network Admin AND the network is enabled.
• OR, the user is NOT a Network Admin AND the network is NOT enabled.

To troubleshoot the Optimizer, use the following methods:

Enable Debug Logging

Set WP_DEBUG to true in your wp-config.php. Logs are prefixed with [Kadence Blocks]: and written to the PHP error log.

define( 'WP_DEBUG', true );

Verify Optimization Status

• Visual Check: Look for the kb-optimized class on the <body> tag.
• Preview Mode: Add ?kadence_optimizer_preview=1 to any URL to view the optimized version, bypassing skip rules (like logged-in user restrictions).

Programmatic Access

You can retrieve stored analysis data via the Store container:

$store = KadenceWP//... (truncated for brevity)
$path = new \KadenceWP\KadenceBlocks\Optimizer\Path\Path( '/my-page/', $post_id );
$analysis = $store->get( $path );

The Ignored_Query_Var_Rule skips optimization when specific query parameters are present. You can add your own custom query variables to this list using the kadence_blocks_optimizer_rule_skip_query_vars filter.

add_filter( 'kadence_blocks_optimizer_rule_skip_query_vars', static fn( array $vars ): array => [
    ...$vars,
    'my_custom_preview',
]);

The Optimizer applies content-visibility: auto to below-the-fold Kadence Row and Column blocks. If a section causes layout shifts (CLS) or requires immediate rendering (like parallax sections), you can exclude it using the kadence_blocks_optimizer_section_lazy_load_excluded_classes filter.

// Exclude specific classes from section lazy loading.
add_filter( 'kadence_blocks_optimizer_section_lazy_load_excluded_classes', static fn( array $classes ): array => [
    ...$classes,
    'my-parallax-section',
]);