WordPress Development

Building Custom Gutenberg Blocks: A Developer’s Practical Introduction

Building Custom Gutenberg Blocks: A Developer's Practical Introduction

For a long time, building custom editing experiences in WordPress meant shortcodes, meta boxes and page builder modules. The block editor changed that. Now you can build custom blocks: components that editors insert, configure and see exactly as they’ll appear on the site.

On client projects, custom blocks are often the difference between a site editors love and one they fear. Instead of explaining complicated layout rules, I give editors a “Testimonial” block, a “Pricing table” block or a “Team member” block. They fill in the fields, and the design takes care of itself.

Block development uses modern JavaScript and React, which puts off some PHP developers. But the tooling has matured a lot, and getting started is far easier than it used to be. Here’s a practical introduction.

When to build a custom block

Before writing a block, check whether you need one:

  • Core blocks handle many needs, especially combined with patterns.
  • Block patterns can create complex layouts from existing blocks, with no code beyond the pattern itself.
  • Block variations can preconfigure an existing block for a specific purpose.
  • Block bindings, introduced in WordPress 6.5, connect core blocks to custom fields and other data sources.

Build a custom block when you need custom markup, structured data input, dynamic content, interactivity or strict design control that patterns can’t provide.

Setting up with create-block

The official create-block tool scaffolds a complete block plugin with the build setup ready:

This creates a plugin folder with:

  • A main PHP file that registers the block.
  • A src folder with block.json, the edit and save components, styles and an index file.
  • A package.json with build scripts using @wordpress/scripts.

npm start watches files and rebuilds as you edit. npm run build creates production-ready files. Activate the plugin in WordPress, and your block appears in the inserter.

block.json: the block’s metadata

block.json describes the block: its name, title, category, attributes, supported features and assets. WordPress reads it both in PHP and JavaScript, making block.json the single source of truth.

Some key parts:

  • name must be unique, with a namespace, like mysite/testimonial.
  • apiVersion 3 is the current version, introduced in WordPress 6.3.
  • attributes define the data the block stores.
  • supports enables built-in features like colour, spacing and typography controls, which automatically respect your theme.json settings.
  • editorScript, editorStyle and style point to built assets. style loads on both the front end and the editor; editorStyle only in the editor.

Registering the block in PHP is a single function call:

Attributes

Attributes are the block’s data. Each has a type and optionally a source, which tells WordPress where to find the value.

  • Attributes with a source like html or attribute are parsed from the saved markup.
  • Attributes without a source are stored as JSON in the block’s comment delimiter in post content.

For text that editors type, sourcing from markup keeps the saved content readable. For settings like toggles, numbers or IDs, storing in the comment delimiter is simpler.

The edit component

The edit function defines what editors see and interact with in the editor. It’s a React component that receives attributes and a setAttributes function:

useBlockProps adds the classes, styles and attributes WordPress needs, including those from supports like colour and spacing. Always spread it onto the outer element.

RichText gives editors inline text editing with formatting controls.

Sidebar controls

For settings that don’t belong inline, use InspectorControls to add panels in the block sidebar:

Static blocks: the save function

For static blocks, the save function returns the markup that’s saved into post content:

The saved HTML is stored in the database. When the post loads in the editor, WordPress runs save again and compares the result with what’s stored.

Block validation and deprecations

If you change the save function after content exists, the stored markup no longer matches. The editor shows a “This block contains unexpected or invalid content” message. To handle changes gracefully, add a deprecation: a record of the old save function and attributes, so WordPress can recognise and migrate old content.

This is the biggest gotcha with static blocks. Plan markup carefully before content is created, and use deprecations when you must change it.

Dynamic blocks

Dynamic blocks render on the server with PHP each time the page loads. The save function returns null, and a render file or callback produces the output.

In block.json:

And in render.php:

Use dynamic blocks when:

  • Content changes over time, like latest posts, product lists or data from an API.
  • You want to be able to change markup without validation errors.
  • Output depends on the current user or other context.

The trade-off is a little more server work on each page load, which caching usually handles.

In the editor, dynamic blocks can show a live preview using the ServerSideRender component, or a custom preview built in JavaScript.

Styling blocks

Keep block styles scoped to the block’s class to avoid conflicts. Use theme.json variables for colours, spacing and fonts, so blocks match the theme:

Use supports in block.json for colour, spacing, typography and borders where possible, rather than building custom controls. Supported features automatically integrate with the theme’s settings and global styles.

Interactivity

For blocks that need front-end behaviour, like tabs, accordions or filters, WordPress 6.5 introduced the Interactivity API. It provides a standard, lightweight way to add interactivity to blocks using directives in markup and small JavaScript stores, without each block loading its own framework.

For simpler needs, a small view script loaded only when the block is present works well. block.json’s viewScript or viewScriptModule fields handle this.

Best practices

  • Use block.json for everything it supports.
  • Use supports instead of custom controls where possible.
  • Escape output in render callbacks.
  • Internationalise strings with the i18n functions.
  • Consider accessibility: semantic markup, keyboard support and proper labels.
  • Keep blocks focused. One block that does one thing well beats a mega block with dozens of options.
  • Put blocks in a plugin, not a theme, so content survives theme changes.

Planning blocks with editors in mind

The best custom blocks come from watching how editors actually work. Before building, I ask the people who’ll use the block what they create most often and where they struggle. Their answers often change the design. A team that publishes case studies weekly might need a block with fixed fields for the client name, the challenge, the solution and the results, rather than a flexible layout that leaves them guessing.

A few principles guide my block design:

  • Fewer options are often better. Every toggle and setting is another decision for the editor and another combination to test.
  • Sensible defaults. A block should look good the moment it’s inserted, before any settings are changed.
  • Clear placeholders. Placeholder text should explain what goes in each field, like “Client’s name and company”.
  • Match the front end. What editors see in the editor should closely match the published result, so there are no surprises.

Testing and maintaining blocks

Blocks are code that lives inside your content for years, so they deserve proper testing. Test new blocks with long and short content, missing fields, every colour option and on small screens. Check them in the editor and on the front end.

When WordPress releases a major version, test your custom blocks on a staging site before updating production. The block editor evolves quickly, and occasionally changes affect custom blocks. Keeping the @wordpress packages in your build tooling up to date also helps your blocks stay compatible with the latest editor features.

Document each block’s purpose and options for editors.

A short guide with screenshots helps new team members get started quickly.

Frequently asked questions

Do I need to know React to build blocks?

Basic React knowledge helps a lot, especially components, props and state. You don’t need to be an expert. The WordPress components and data packages handle much of the complexity.

Should I build static or dynamic blocks?

Static blocks are simpler and fast to render, but changing markup later requires deprecations. Dynamic blocks are more flexible and better for changing data. Many developers default to dynamic blocks for anything likely to evolve.

Can I build blocks without a build step?

It’s possible using plain JavaScript and the wp global, but you lose JSX and modern tooling. The create-block setup is the recommended approach.

Where should custom blocks live?

In a plugin. If blocks live in a theme, switching themes leaves content with blocks WordPress no longer recognises.

Final thoughts

Custom blocks let you design the editing experience as carefully as the front end. Start with create-block, define everything you can in block.json, use supports and theme.json variables to stay consistent, choose static or dynamic rendering deliberately and keep blocks focused and accessible. Your editors get components that are easy to use and hard to break, and your sites stay consistent long after launch.