How to Build a Custom Gutenberg Block Without Losing Your Mind

You ship a client site, everyone’s happy, and three months later the content editor opens a page and gets the red bar: This block contains unexpected or invalid content. One button says “Attempt Block Recovery”. The other says “Convert to HTML”. Whatever they click, something is now wrong on a live page and nobody noticed for a week.

That single failure mode is responsible for most of the pain people associate with block editor development. It isn’t React that’s hard. It isn’t webpack. It’s the fact that a static block stores its own markup in post_content and then re-validates that markup against your save() function on every edit, forever.

Here’s how we build a custom Gutenberg block at SemiColonWeb so that doesn’t happen: the decision tree before you write any code, the parts of the scaffold that actually matter, and the 2026-era APIs (Interactivity, block bindings, metadata collections) that replaced a lot of what the older tutorials teach.

First, decide whether you need a block at all

Every custom block is a permanent maintenance liability. It has a build step, a JS dependency tree, and content in the database that only it can render. So the first question is whether core already does it.

Four things to rule out, in order of cheapness:

• Block styles. registerblockstyle() adds a class-based variant to a core block. A “boxed quote” is a style, not a block.
• Block variations. Same block, different preset attributes and inner block template. A “Team Grid” is usually core/group plus core/columns with a locked template.
• Patterns. If it’s a layout the client assembles once per page and then edits freely, it’s a pattern. Patterns are just serialised core blocks: zero runtime cost, zero upgrade risk.
• Block bindings. Since WP 6.5, you can bind a core paragraph, heading, image or button attribute straight to post meta. If the requirement is “show the custom field value here, styled like the rest of the site”, that’s a binding plus a registered meta key. No custom block.

You build a custom block when the thing has its own data shape, its own editing affordances, and rendering logic that touches the database at view time. Pricing card with a query for the current plan? Block. Fancy divider? Not a block.

Scaffold once, then read what it made

Start with the official generator. Don’t hand-roll a webpack config in 2026.

npx @wordpress/create-block@latest scw-pricing-card \
  --namespace scw \
  --variant dynamic \
  --no-plugin   # omit the plugin header if you're dropping it into an existing plugin
cd scw-pricing-card
npm run start   # wp-scripts watch build, sourcemaps on

The --variant dynamic flag matters. It gives you a render.php and no save() markup, which is the shape you want for about 80% of client work.

The scaffold produces a src/ folder and a build/ folder. Only build/ is registered. If you’ve ever had a block silently fail to appear, check that you’re pointing registerblocktype() at the build directory, not src/.

block.json is the whole API surface

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "scw/pricing-card",
  "title": "Pricing Card",
  "category": "design",
  "icon": "money-alt",
  "textdomain": "scw-blocks",
  "attributes": {
    "tier":        { "type": "string",  "default": "Standard" },
    "price":       { "type": "string",  "default": "49" },
    "highlighted": { "type": "boolean", "default": false }
  },
  "supports": {
    "html": false,
    "anchor": true,
    "color": { "background": true, "text": true },
    "spacing": { "padding": true, "margin": [ "top", "bottom" ] },
    "typography": { "fontSize": true, "lineHeight": true },
    "interactivity": true
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css",
  "viewScriptModule": "file:./view.js",
  "render": "file:./render.php"
}

Two lines earn their keep. "supports" hands you colour, spacing and typography controls for free, wired into theme.json, which means the block inherits the site’s design tokens instead of inventing new ones. And "html": false removes the “Edit as HTML” option, which is the single most common way editors corrupt a block. That’s the same instinct behind everything in our client-proof admin handover process: remove the loaded gun.

Note "apiVersion": 3. The post editor canvas is an iframe at v3. Styles you enqueue onto the admin page do not reach inside it. Use editorStyle, or addeditorstyle() from the theme, and nothing else.

How to build a WordPress block that survives your own edits

Static blocks serialise their output into post_content wrapped in HTML comments. On load, WordPress re-runs save() with the stored attributes and string-compares the result against what’s in the database. Any difference, even an attribute order change caused by a @wordpress/block-editor update, triggers the invalid content warning.

Dynamic blocks store this:

<!-- wp:scw/pricing-card {"tier":"Pro","price":"149","highlighted":true} /-->

That’s it. No markup to validate. The output is generated at render time by render.php:

<?php
/**

@var array    $attributes
@var string   $content    Serialised InnerBlocks output.
@var WP_Block $block
 */
$extra = $attributes['highlighted'] ? 'scw-pricing-card is-highlighted' : 'scw-pricing-card';
// getblockwrapper_attributes() emits the classes and inline styles generated by "supports".
?>
<div <?php echo getblockwrapper_attributes( array( 'class' => $extra ) ); ?>>
	<h3 class="scw-pricing-card__tier"><?php echo esc_html( $attributes['tier'] ); ?></h3>
	<p class="scw-pricing-card__price">
		<span class="scw-pricing-card__currency">&pound;</span><?php echo esc_html( $attributes['price'] ); ?>
	</p>
	<?php echo $content; // Already rendered and escaped by the block renderer. ?>
</div>

Change the markup next year, hit save on the PHP file, every existing instance updates. No migration. No recovery prompts.

The trade-off is real and you should know it. Dynamic blocks cost PHP on every uncached request, and their content is invisible to anything reading post_content directly: some search indexers, some export tools, the default WP REST API content.raw field. On a heavily cached site that cost rounds to zero, but on a page-cache-hostile setup (logged-in users, personalised content), measure it. Our breakdown of the caching layers covers where those requests actually land.

When you do ship static, write the deprecation first

registerBlockType( metadata.name, {
	edit: Edit,
	save: Save,
	deprecated: [ {
		attributes: { ...metadata.attributes, price: { type: 'number' } },
		save( { attributes } ) {
			// Exact copy of the OLD save output. Do not tidy it up.
			return <div className="pricing">{ attributes.price }</div>;
		},
		migrate( attributes ) {
			return { ...attributes, price: String( attributes.price ) };
		},
	} ],
} );

The deprecated save must be a byte-faithful copy of the old one. People break this by “cleaning up” the old function while they move it. Copy, paste, don’t touch.

Build the editor UI the client will actually use

The edit component should look like the front end. Not approximately, exactly, because editors judge whether a block is broken by whether the preview matches the page.

import { __ } from '@wordpress/i18n';
import { useBlockProps, useInnerBlocksProps, InspectorControls, RichText } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';

const TEMPLATE = [
	[ 'core/list', {}, [ [ 'core/list-item', { content: __( 'Unlimited projects', 'scw-blocks' ) } ] ] ],
	[ 'core/buttons', { lock: { remove: true, move: false } } ],
];

export default function Edit( { attributes, setAttributes } ) {
	const { tier, price, highlighted } = attributes;

	const blockProps = useBlockProps( {
		className: highlighted ? 'scw-pricing-card is-highlighted' : 'scw-pricing-card',
	} );

	// Spread inner blocks onto the same wrapper so the editor DOM matches render.php.
	const innerBlocksProps = useInnerBlocksProps( blockProps, {
		template: TEMPLATE,
		templateLock: 'insert', // Children can be edited and reordered, not added or deleted.
	} );

	return (
		<>
			<InspectorControls>
				<PanelBody title={ __( 'Card options', 'scw-blocks' ) }>
					<ToggleControl
						__nextHasNoMarginBottom
						label={ __( 'Highlight this tier', 'scw-blocks' ) }
						checked={ highlighted }
						onChange={ ( value ) => setAttributes( { highlighted: value } ) }
					/>
				</PanelBody>
			</InspectorControls>

			<div { ...innerBlocksProps }>
				<RichText
					tagName="h3"
					value={ tier }
					allowedFormats={ [] }
					onChange={ ( value ) => setAttributes( { tier: value } ) }
					placeholder={ __( 'Tier name', 'scw-blocks' ) }
				/>
				{ innerBlocksProps.children }
			</div>
		</>
	);
}

Three opinions baked into that snippet. allowedFormats={ [] } on the tier stops someone pasting bold red Comic Sans into a heading. templateLock: 'insert' is the sweet spot for client sites: editable content, fixed structure. Put every control in InspectorControls rather than rendering settings inline in the canvas, because inline controls confuse people about what’s content and what’s configuration.

One more thing that audits always catch: RichText with a placeholder is not a label. If your block has form-like controls in the canvas, they need accessible names. We wrote up the recurring offenders in the five accessibility failures auditors always find.

Front-end behaviour without shipping React

The old pattern was to enqueue a viewScript that queried the DOM and bolted on listeners. It worked, but you ended up hand-rolling state for every toggle, tab and filter.

Since WP 6.5, the Interactivity API gives you a declarative directive system with a runtime of a few kilobytes. Declare "interactivity": true in supports, point viewScriptModule at your file, and write directives in the PHP output:

<div
	<?php echo getblockwrapper_attributes(); ?>
	data-wp-interactive="scw/pricing"
	<?php echo wpinteractivitydatawpcontext( array( 'isOpen' => false ) ); ?>
>
	<button
		data-wp-on--click="actions.toggle"
		data-wp-bind--aria-expanded="context.isOpen"
	><?php eschtmle( 'What is included', 'scw-blocks' ); ?></button>

	<div data-wp-bind--hidden="!context.isOpen"><?php echo $content; ?></div>
</div>

import { store, getContext } from '@wordpress/interactivity';

store( 'scw/pricing', {
	actions: {
		toggle() {
			const context = getContext();
			context.isOpen = ! context.isOpen; // Mutating the proxy re-renders bound directives.
		},
	},
} );

Note the ! prefix in data-wp-bind--hidden. Negation is supported inline, which saves you a derived state entry for every trivial inverse.

The honest caveat: the Interactivity API is worth it for anything with state that changes. For a one-off scroll reveal or a hover effect, plain CSS plus an IntersectionObserver is smaller and less to learn. We’ve argued the performance side of that in micro-interactions without wrecking performance.

Registering twenty blocks without twenty file reads

Each registerblocktype( __DIR__ . '/build/thing' ) call reads and parses a JSON file on every single request. With one block, irrelevant. With a plugin shipping 25, that’s 25 filesystem hits per page load on a cold object cache.

WordPress 6.8 added wpregisterblocktypesfrommetadatacollection(), which reads one pre-compiled PHP array instead. Generate it in the build:

wp-scripts build --blocks-manifest

add_action( 'init', function () {
	$build = __DIR__ . '/build';

	if ( functionexists( 'wpregisterblocktypesfrommetadata_collection' ) ) {
		wpregisterblocktypesfrommetadatacollection( $build, $build . '/blocks-manifest.php' );
		return;
	}

	// Fallback for 6.7 and earlier.
	foreach ( (array) glob( $build . '/*/block.json' ) as $file ) {
		registerblocktype( dirname( $file ) );
	}
} );

Also: run wp-env start for local development rather than testing on the client’s staging box. It gives you a throwaway WordPress with your plugin mounted, and wp-env run cli wp ... for WP-CLI. Resetting a broken block’s content is one command, not a database restore.

What breaks in production

Five things we see repeatedly on handover:

• Editor styles that don’t load. API v3 iframe. Declare editorStyle, never wpenqueuestyle on adminenqueuescripts.
• Block CSS loading on every page. Declare styles in block.json and WordPress only enqueues them on pages containing the block, provided the theme doesn’t call wpenqueueglobalstyles incorrectly or force shouldloadseparatecoreblockassets to false.
• ServerSideRender in the editor. It fires a REST request on every attribute change. On a shared host that’s a visible lag of 300ms or more per keystroke. Render in JS, render in PHP, don’t use both for live preview.
• Attribute drift. Adding a new attribute with no default means existing content gets undefined. Always set a default.
• Uncleaned revisions. Blocks with large attribute payloads inflate wp_posts fast because every autosave copies them. Worth reading alongside our notes on revisions and autoloaded option bloat.

If the project is mostly layout rather than custom data, weigh whether a theme that already ships the patterns is cheaper than a block library you have to maintain. CanvasWP exists for that reason: most “we need a custom block” briefs are really “we need this layout to be editable by a non-developer”.