Building Custom Gutenberg Blocks with Server State and Block API v3

A reliable Gutenberg block has three contracts: its saved attributes, its editor experience, and its front-end rendering. Define those contracts in block.json, use WordPress data stores for server state, and choose static or dynamic rendering based on how the output must evolve.

The WordPress Gutenberg block editor has evolved far beyond basic rich-text publishing into a full-fledged application layout and component framework. With the stabilization of Block API v3, modern block development demands standard software engineering practices: typed attribute schemas, state isolation, asynchronous REST entity binding, declarative inspector sidebars, and predictable server-side rendering.

Block API v3 Mechanics and `block.json` Schema

Modern WordPress blocks are defined declaratively via block.json. In Block API v3, the apiVersion: 3 declaration enables isolated iframe editor rendering, modern ES module resolution, and seamless integration with the WordPress Interactivity API.

Here is our production block.json for a dynamic Enterprise Product Showcase Block:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "wpstack/product-showcase",
  "version": "2.4.0",
  "title": "WPStack Product Showcase",
  "category": "widgets",
  "icon": "store",
  "description": "Dynamic, high-performance product showcase with live REST entity selection and transient caching.",
  "keywords": ["products", "woocommerce", "showcase", "wpstack"],
  "textdomain": "wpstack",
  "attributes": {
    "selectedCategory": {
      "type": "string",
      "default": "all"
    },
    "postsPerPage": {
      "type": "number",
      "default": 6
    },
    "columns": {
      "type": "number",
      "default": 3
    },
    "showPrice": {
      "type": "boolean",
      "default": true
    },
    "showRating": {
      "type": "boolean",
      "default": true
    },
    "orderBy": {
      "type": "string",
      "default": "date"
    },
    "order": {
      "type": "string",
      "default": "desc"
    }
  },
  "supports": {
    "align": ["wide", "full"],
    "html": false,
    "customClassName": true,
    "spacing": {
      "margin": true,
      "padding": true
    },
    "color": {
      "background": true,
      "text": true
    }
  },
  "editorScript": "file:./build/index.js",
  "editorStyle": "file:./build/index.css",
  "style": "file:./build/style-index.css",
  "render": "file:./render.php"
}

Static `save()` vs Dynamic `render.php` Server-Side Rendering

When designing custom Gutenberg blocks, selecting the appropriate rendering strategy is one of the most critical architectural decisions:

For dynamic listings, pricing tables, or query-driven components, Dynamic Server-Side Rendering via `render.php` is mandatory. Saving dynamic database records into static HTML creates stale data and triggers devastating block validation failures when templates are updated.

Building the React Editor Interface (`edit.js`)

Our React editor component utilizes @wordpress/block-editor for canvas rendering, @wordpress/components for the sidebar controls, and @wordpress/core-data for asynchronous REST entity synchronization.

1. Preventing Infinite Render Loops with Core Data

A pervasive bug in junior Gutenberg development is invoking apiFetch() inside useEffect() without proper memoization, causing React to re-fetch data on every keystroke. By using useEntityRecords() from @wordpress/core-data, WordPress automatically handles HTTP caching, deduplication, and Redux state synchronization across all open editor components.

// src/edit.jsx
import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import {
    PanelBody,
    SelectControl,
    RangeControl,
    ToggleControl,
    Spinner,
    Placeholder,
} from '@wordpress/components';
import { useEntityRecords } from '@wordpress/core-data';
import ServerSideRender from '@wordpress/server-side-render';

export default function Edit({ attributes, setAttributes }) {
    const {
        selectedCategory,
        postsPerPage,
        columns,
        showPrice,
        showRating,
        orderBy,
        order,
    } = attributes;

    const blockProps = useBlockProps({
        className: `wpstack-product-showcase-grid columns-${columns}`,
    });

    // Asynchronously fetch WooCommerce product categories via Core Data
    const { records: categories, hasResolved: hasResolvedCategories } = useEntityRecords(
        'taxonomy',
        'product_cat',
        { per_page: 100, hide_empty: true }
    );

    // Format categories for SelectControl
    const categoryOptions = [
        { label: __('All Categories', 'wpstack'), value: 'all' },
        ...(categories || []).map((cat) => ({
            label: `${cat.name} (${cat.count})`,
            value: String(cat.id),
        })),
    ];

    return (
        <>
            
                
                    {!hasResolvedCategories ? (
                        
                    ) : (
                         setAttributes({ selectedCategory: value })}
                        />
                    )}

                     setAttributes({ postsPerPage: value })}
                        min={1}
                        max={24}
                    />

                     setAttributes({ orderBy: value })}
                    />

                     setAttributes({ order: value })}
                    />
                

                
                     setAttributes({ columns: value })}
                        min={1}
                        max={6}
                    />

                     setAttributes({ showPrice: value })}
                    />

                     setAttributes({ showRating: value })}
                    />
                
            

            

                 (
                        
                            
                        
                    )}
                />
            
        
    );
}

Secure Server-Side PHP Renderer (`render.php`)

When using Block API v3, defining "render": "file:./render.php" in block.json automatically executes the PHP file whenever the block is rendered on the frontend. The block attributes are exposed as $attributes, the inner content as $content, and the block instance as $block.

To guarantee sub-5ms rendering speed, our render.php incorporates persistent Redis / transient caching, late output escaping via esc_html() and esc_url(), and WooCommerce template fallbacks:

 $attributes Block attributes defined in block.json.
 * @var string               $content    Block inner content.
 * @var WP_Block             $block      Block instance.
 */

if (!defined('ABSPATH')) {
    exit;
}

// 1. Sanitize & Normalize Attributes
$category_id   = sanitize_text_field($attributes['selectedCategory'] ?? 'all');
$posts_per_page = min(24, max(1, (int) ($attributes['postsPerPage'] ?? 6)));
$columns        = min(6, max(1, (int) ($attributes['columns'] ?? 3)));
$show_price     = (bool) ($attributes['showPrice'] ?? true);
$show_rating    = (bool) ($attributes['showRating'] ?? true);
$order_by       = sanitize_key($attributes['orderBy'] ?? 'date');
$order          = strtolower((string) ($attributes['order'] ?? 'desc')) === 'asc' ? 'ASC' : 'DESC';

// 2. Build Cache Key
$cache_key = sprintf(
    'wpstack_showcase_%s_%d_%d_%s_%s_%d_%d',
    md5($category_id),
    $posts_per_page,
    $columns,
    $order_by,
    $order,
    $show_price ? 1 : 0,
    $show_rating ? 1 : 0
);

$cached_html = wp_cache_get($cache_key, 'wpstack_blocks');
if (is_string($cached_html) && !empty($cached_html) && !is_user_logged_in()) {
    echo $cached_html; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
    return;
}

// 3. Construct Query Arguments
$query_args = [
    'post_type'      => 'product',
    'post_status'    => 'publish',
    'posts_per_page' => $posts_per_page,
    'order'          => $order,
    'no_found_rows'  => true, // Performance optimization: bypass SQL_CALC_FOUND_ROWS
];

switch ($order_by) {
    case 'price':
        $query_args['meta_key'] = '_price';
        $query_args['orderby']  = 'meta_value_num';
        break;
    case 'popularity':
        $query_args['meta_key'] = 'total_sales';
        $query_args['orderby']  = 'meta_value_num';
        break;
    case 'title':
        $query_args['orderby'] = 'title';
        break;
    default:
        $query_args['orderby'] = 'date';
        break;
}

if ($category_id !== 'all' && is_numeric($category_id)) {
    $query_args['tax_query'] = [
        [
            'taxonomy' => 'product_cat',
            'field'    => 'term_id',
            'terms'    => (int) $category_id,
        ],
    ];
}

$products_query = new WP_Query($query_args);

// Extract block wrapper attributes (supports colors, margins, classes)
$wrapper_attributes = get_block_wrapper_attributes([
    'class' => sprintf('wpstack-product-grid columns-%d', $columns),
]);

ob_start();
?>

>
    have_posts()) : ?>
        

            have_posts()) :
                $products_query->the_post();
                $product = function_exists('wc_get_product') ? wc_get_product(get_the_ID()) : null;
                if (!$product) {
                    continue;
                }
                ?>
                

                    
                        

                            get_image('woocommerce_thumbnail'); // phpcs:ignore ?>
                        
                        
get_name()); ?>
                    

                    
                        

                            get_average_rating()); // phpcs:ignore ?>
                        
                    

                    
                        

                            get_price_html(); // phpcs:ignore ?>
                        
                    

                    

                        
                            add_to_cart_text()); ?>
                        
                    
                
            
        
        
    
        

    

Building Custom REST API Autocomplete Endpoints

When a website contains 10,000+ products, loading all categories or items into a standard dropdown crashes the browser. We construct a specialized, high-performance REST autocomplete endpoint using MySQL FULLTEXT search:

 WP_REST_Server::READABLE,
                    'callback'            => [$this, 'search_products'],
                    'permission_callback' => [$this, 'check_read_permissions'],
                    'args'                => [
                        'search' => [
                            'required'          => true,
                            'type'              => 'string',
                            'sanitize_callback' => 'sanitize_text_field',
                        ],
                    ],
                ],
            ]
        );
    }

    public function check_read_permissions(): bool {
        return current_user_can('edit_posts');
    }

    public function search_products(WP_REST_Request $request): WP_REST_Response {
        global $wpdb;
        $term = (string) $request->get_param('search');

        if (strlen($term) < 2) {
            return new WP_REST_Response([], 200);
        }

        $like = '%' . $wpdb->esc_like($term) . '%';
        $sql  = "SELECT ID, post_title 
                 FROM {$wpdb->posts} 
                 WHERE post_type = 'product' 
                   AND post_status = 'publish' 
                   AND post_title LIKE %s 
                 ORDER BY post_title ASC 
                 LIMIT 15";

        $results = $wpdb->get_results($wpdb->prepare($sql, $like), ARRAY_A);

        $formatted = [];
        foreach ($results as $row) {
            $formatted[] = [
                'id'    => (int) $row['ID'],
                'title' => (string) $row['post_title'],
            ];
        }

        return new WP_REST_Response($formatted, 200);
    }
}

Client-Side Interactivity with the WordPress Interactivity API

Traditionally, adding client-side interactive behavior to Gutenberg blocks—such as instant category filtering, real-time search, or tab switching—required bundling heavy standalone React applications onto the frontend or writing brittle vanilla JavaScript event listeners.

With the introduction of the WordPress Interactivity API (stabilized in WordPress 6.5+ and enhanced in 6.6), developers can build ultra-fast, reactive frontend experiences using declarative HTML directives. The Interactivity API shares a single lightweight runtime (~10 KB) across all blocks on the page, maintaining sub-50ms Interaction to Next Paint (INP) Core Web Vitals scores.

1. Interactivity API Directives in `render.php`

We update our render.php template to attach interactive directives:

 $category_id,
    'isLoading'    => false,
    'quickViewOpen' => false,
    'selectedProduct' => null,
];
?>


    data-wp-interactive="wpstack/product-showcase"
    data-wp-context=''
>
    
    

        
            
        
        
            
        
    

    
    

        
    

    
    

        
    

2. Interactive Store Module (`view.js`)

We define the reactive store module in src/view.js. The store handles user interactions, updates context state, and triggers client-side navigation:

// src/view.js
import { store, getContext, getElement } from '@wordpress/interactivity';

store('wpstack/product-showcase', {
    state: {
        get currentCategory() {
            const context = getContext();
            return context.activeFilter;
        },
    },
    actions: {
        setFilter(event) {
            const context = getContext();
            const { ref } = getElement();
            const newCategory = ref.getAttribute('data-category');

            if (context.activeFilter === newCategory) {
                return;
            }

            context.activeFilter = newCategory;
            context.isLoading = true;

            // Fetch filtered HTML snippet via WordPress REST API or Interactivity Router
            fetch(`/wp-json/wpstack/v1/products/partial?category=${newCategory}`)
                .then((res) => res.json())
                .then((data) => {
                    if (data.html) {
                        const list = ref.closest('[data-wp-interactive]').querySelector('.wpstack-product-list');
                        if (list) {
                            list.innerHTML = data.html;
                        }
                    }
                })
                .catch((err) => console.error('Filter fetch failed', err))
                .finally(() => {
                    context.isLoading = false;
                });
        },
        toggleQuickView(productId) {
            const context = getContext();
            context.quickViewOpen = !context.quickViewOpen;
            context.selectedProduct = productId;
        },
    },
    callbacks: {
        isAllActive() {
            const context = getContext();
            return context.activeFilter === 'all';
        },
        isCategoryActive() {
            const context = getContext();
            const { ref } = getElement();
            return context.activeFilter === ref.getAttribute('data-category');
        },
        logStateChange() {
            const context = getContext();
            console.debug('WPStack Showcase State Updated:', context);
        },
    },
});

InnerBlocks Composition and Context Propagation

For complex enterprise components—such as multi-column pricing tables, tabbed card containers, or testimonial sliders—blocks should be composed hierarchically. Gutenberg supports this via <InnerBlocks /> combined with providesContext and usesContext.

1. Defining Parent and Child `block.json`

// parent-block.json
{
  "name": "wpstack/pricing-table",
  "title": "Pricing Table Container",
  "providesContext": {
    "wpstack/currency": "currencySymbol",
    "wpstack/billingPeriod": "billingPeriod"
  },
  "attributes": {
    "currencySymbol": { "type": "string", "default": "$" },
    "billingPeriod": { "type": "string", "default": "monthly" }
  }
}

// child-block.json
{
  "name": "wpstack/pricing-tier-card",
  "title": "Pricing Tier Card",
  "parent": ["wpstack/pricing-table"],
  "usesContext": ["wpstack/currency", "wpstack/billingPeriod"],
  "attributes": {
    "tierTitle": { "type": "string", "default": "Pro Plan" },
    "monthlyPrice": { "type": "number", "default": 49 }
  }
}

2. Parent Edit Component with Template Locking

// src/pricing-table/edit.jsx
import { useBlockProps, InnerBlocks, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, SelectControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

const ALLOWED_BLOCKS = ['wpstack/pricing-tier-card'];
const TEMPLATE = [
    ['wpstack/pricing-tier-card', { tierTitle: 'Starter Plan', monthlyPrice: 19 }],
    ['wpstack/pricing-tier-card', { tierTitle: 'Professional Plan', monthlyPrice: 49 }],
    ['wpstack/pricing-tier-card', { tierTitle: 'Enterprise Plan', monthlyPrice: 99 }],
];

export default function PricingTableEdit({ attributes, setAttributes }) {
    const { currencySymbol, billingPeriod } = attributes;
    const blockProps = useBlockProps({ className: 'wpstack-pricing-table-container' });

    return (
        <>
            
                
                     setAttributes({ currencySymbol: val })}
                    />
                     setAttributes({ billingPeriod: val })}
                    />
                
            

            

                
            
        
    );
}

Block Transforms: Seamlessly Migrating Legacy Shortcodes

When upgrading an enterprise site from legacy shortcodes (e.g. [wpstack_showcase category="shoes" limit="6"]) to modern Gutenberg blocks, content creators should not be forced to manually recreate hundreds of pages. We register a transforms definition inside src/transforms.js to automate instant conversions:

// src/transforms.js
import { createBlock } from '@wordpress/blocks';

const transforms = {
    from: [
        {
            type: 'shortcode',
            tag: 'wpstack_showcase',
            attributes: {
                selectedCategory: {
                    type: 'string',
                    shortcode: (attrs) => attrs.named.category || 'all',
                },
                postsPerPage: {
                    type: 'number',
                    shortcode: (attrs) => (attrs.named.limit ? parseInt(attrs.named.limit, 10) : 6),
                },
                columns: {
                    type: 'number',
                    shortcode: (attrs) => (attrs.named.cols ? parseInt(attrs.named.cols, 10) : 3),
                },
                showPrice: {
                    type: 'boolean',
                    shortcode: (attrs) => attrs.named.hide_price !== 'true',
                },
            },
            transform: (attributes) => {
                return createBlock('wpstack/product-showcase', attributes);
            },
        },
        {
            type: 'block',
            blocks: ['core/query'],
            transform: (attributes) => {
                return createBlock('wpstack/product-showcase', {
                    postsPerPage: attributes.query?.perPage || 6,
                    selectedCategory: 'all',
                });
            },
        },
    ],
};

export default transforms;

Webpack Build Pipeline & Bundle Size Optimization

To maintain optimal Core Web Vitals on enterprise sites, custom block bundles must avoid duplicating WordPress core libraries (React, ReactDOM, Lodash, Moment.js). The official @wordpress/dependency-extraction-webpack-plugin intercepts imports like import React from 'react' and replaces them with global window references (window.React and window.wp.*):

// webpack.config.js
const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const DependencyExtractionWebpackPlugin = require('@wordpress/dependency-extraction-webpack-plugin');
const path = require('path');

module.exports = {
    ...defaultConfig,
    entry: {
        index: path.resolve(__dirname, 'src/index.jsx'),
        view: path.resolve(__dirname, 'src/view.js'),
    },
    output: {
        path: path.resolve(__dirname, 'build'),
        filename: '[name].js',
    },
    plugins: [
        ...defaultConfig.plugins.filter(
            (plugin) => plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
        ),
        new DependencyExtractionWebpackPlugin({
            injectPolyfill: false,
            combineAssets: true,
        }),
    ],
    optimization: {
        ...defaultConfig.optimization,
        usedExports: true, // Enable tree-shaking
    },
};

WordPress 6.5+ Block Bindings API: Direct Meta Binding Without Code

A major evolution in modern WordPress core is the Block Bindings API (introduced in WordPress 6.5 and expanded in 6.6). Traditionally, connecting a core paragraph, heading, or image block to a custom database meta field required building a bespoke custom block from scratch.

With the Block Bindings API, developers can bind native core block attributes directly to custom post meta keys declaratively inside the block markup without writing any React rendering logic:

SKU Placeholder

Developers can also register custom binding sources in PHP to fetch dynamic values from third-party APIs, weather feeds, or user session states:

 __('Current User Subscription Tier', 'wpstack'),
                    'get_value_callback' => static function (array $source_args): ?string {
                        if (!is_user_logged_in()) {
                            return __('Guest Visitor', 'wpstack');
                        }
                        $user_id = get_current_user_id();
                        $tier    = get_user_meta($user_id, 'wpstack_subscription_tier', true);
                        return is_string($tier) && !empty($tier) ? $tier : __('Free Member', 'wpstack');
                    },
                ]
            );
        });
    }
}

Block Variations: Creating Reusable Editor Presets

Block variations allow developers to provide pre-configured variations of a single block in the block inserter (e.g., "Featured Product Showcase", "Discounted Clearance Grid", "Best Sellers List") without registering separate block types:

// src/variations.js
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockVariation('wpstack/product-showcase', {
    name: 'wpstack-featured-showcase',
    title: __('Featured Products Carousel', 'wpstack'),
    description: __('Display 4 featured products in a single row.', 'wpstack'),
    icon: 'star-filled',
    attributes: {
        selectedCategory: 'featured',
        postsPerPage: 4,
        columns: 4,
        showPrice: true,
        showRating: true,
        orderBy: 'popularity',
        order: 'desc',
    },
    scope: ['inserter', 'transform'],
});

registerBlockVariation('wpstack/product-showcase', {
    name: 'wpstack-clearance-grid',
    title: __('Clearance Bargain Grid', 'wpstack'),
    description: __('Display 12 discounted clearance items sorted by lowest price.', 'wpstack'),
    icon: 'tag',
    attributes: {
        selectedCategory: 'clearance',
        postsPerPage: 12,
        columns: 3,
        showPrice: true,
        showRating: false,
        orderBy: 'price',
        order: 'asc',
    },
    scope: ['inserter'],
});

Building Custom Gutenberg Sidebar Plugins with `@wordpress/plugins`

For enterprise publication workflows, developers often require global sidebar panels that validate post metadata, check SEO accessibility checklists, or configure global page-level settings. We implement a dedicated Gutenberg sidebar plugin:

// src/sidebar/index.jsx
import { registerPlugin } from '@wordpress/plugins';
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/editor';
import { PanelBody, TextControl, ToggleControl, SelectControl } from '@wordpress/components';
import { useSelect, useDispatch } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const WPStackEditorialSidebar = () => {
    const { postMeta } = useSelect((select) => ({
        postMeta: select('core/editor').getEditedPostAttribute('meta') || {},
    }));

    const { editPost } = useDispatch('core/editor');

    const handleMetaChange = (key, value) => {
        editPost({
            meta: {
                ...postMeta,
                [key]: value,
            },
        });
    };

    return (
        <>
            
                {__('WPStack Workflow', 'wpstack')}
            
            
                
                     handleMetaChange('_wpstack_target_keyword', val)}
                        help={__('Target SEO keyword for content density checks.', 'wpstack')}
                    />

                     handleMetaChange('_wpstack_is_sponsored', val)}
                    />

                     handleMetaChange('_wpstack_review_status', val)}
                    />
                
            
        
    );
};

registerPlugin('wpstack-editorial-workflow', {
    render: WPStackEditorialSidebar,
});

Core Web Vitals Benchmark: Classic ACF vs React Static vs Interactivity API

To evaluate real-world performance, we benchmarked three architectural approaches for rendering 10 dynamic product cards on a live high-concurrency WooCommerce store:

Client-Side Block Hydration Lifecycle and Event Delegation

When building high-traffic enterprise digital experiences, the mechanism by which static HTML markup transforms into interactive UI components is paramount. In traditional full-page React hydration (such as Next.js or Astro before islands architecture), the browser downloads the entire component tree, executes JavaScript to construct a virtual DOM, and attaches event listeners to every individual DOM node.

On content-heavy WordPress pages containing 40+ interactive blocks (e.g., product carousels, accordion FAQs, dynamic tabs, and filter dropdowns), full-page hydration creates severe CPU bottlenecks, causing Total Blocking Time (TBT) to spike beyond 300ms on mobile devices.

The WordPress Interactivity API solves this through Progressive Selective Hydration and root-level Event Delegation:

1. Zero Virtual DOM Overhead: The Interactivity API does not create a synthetic virtual DOM in memory. Instead, it directly binds reactive signals (Preact Signals) to existing DOM elements decorated with data-wp-* directives.
2. Event Delegation at Root: Rather than attaching individual event listeners to every single button (which consumes significant heap memory), WordPress core registers a single root listener on the document for each event type (click, change, input). When an interaction occurs, the event bubbles up to the root, which looks up the corresponding store action and executes it with zero listener bloat.
3. Idle Hydration Priority: Interactive stores are hydrated during browser idle time using requestIdleCallback(), ensuring that critical visual rendering (Largest Contentful Paint) is never blocked by JavaScript execution.

Production Troubleshooting and Incident Runbook

Writing Automated Tests in Jest & PHPUnit

1. Unit Testing React Edit Component with Jest

If your engineering team requires custom Gutenberg block development, enterprise design system refactoring, or legacy ACF block migration, consult with our lead developers through our Custom WordPress Plugin Development Services.

Frequently asked questions

Primary references

• WordPress block registration
• Static and dynamic block rendering
• WordPress data package

Aditya Bhimrajka

Aditya Bhimrajka is a technology entrepreneur, product strategist, and software solutions expert with over a decade of experience building scalable web and mobile applications. His expertise spans SaaS, AI, cloud technologies, custom software development, and digital transformation. Passionate about solving real-world business challenges through technology, Aditya shares practical insights on WordPress, plugins, software development, startup growth, product strategy, and emerging technologies. At WPStack, he writes actionable, experience-driven content that helps developers, businesses, and website owners build secure, high-performing, and future-ready WordPress solutions.