WordPress Block Development Guide 2026

Published April 21, 2026

WordPress Block Development Guide

Custom Gutenberg blocks package reusable content patterns into intuitive editor components. Built with React and registered via block.json, custom blocks integrate seamlessly with the native WordPress editor experience — no third-party dependencies required.

Block Anatomy

Every block consists of three parts:

• block.json: The manifest declaring name, version, attributes, supports, and file references
• edit.js: The React component that renders in the editor
• save.js: The function that returns the static HTML saved to the database (or null for dynamic blocks)

Scaffolding a Block

npx @wordpress/create-block my-block --template @wordpress/create-block-tutorial-template

This generates the complete block boilerplate with webpack configuration, ESLint setup, and npm scripts. Run npm start for development watch mode and npm run build for production.

Block Attributes

Attributes are the data model for your block — declared in block.json and accessible in edit and save functions. Common types: string, number, boolean, array, object. Attributes can source from the block's saved HTML (selector-based), post meta, or the block's comment delimiters. Changes to attribute types in existing blocks require deprecation handling.

Using Block Controls

WordPress provides built-in editor controls via @wordpress/block-editor:

• InspectorControls: Settings panel in the right sidebar
• BlockControls: Toolbar above the block
• RichText: Editable text with formatting options
• MediaUpload: Image and media selection
• InnerBlocks: Nested block area (container blocks)

Dynamic Blocks (Server-Side Rendering)

Dynamic blocks render their output with PHP on every page load — ideal for blocks that display live data (recent posts, current user info, live pricing). Set save to return null and register a render_callback in register_block_type(). The render callback receives block attributes and generates HTML server-side.

Block Styles and Variations

Block styles add CSS classes that change block appearance (e.g., a "rounded" button style). Register with register_block_style(). Block variations create preset configurations of existing blocks — register with registerBlockVariation() in JavaScript. Both extend blocks without creating new block types, keeping the editor clean.

Test custom blocks across SiteICO's staging environments before deploying — block output must be consistent across PHP versions to avoid serialization issues.