WordPress Custom Block Development Guide: Build, Register, and Maintain Gutenberg Blocks
Gutenbergcustom blocksblock editorblock.jsonJavaScriptPHP

WordPress Custom Block Development Guide: Build, Register, and Maintain Gutenberg Blocks

CCode Craft Studio Editorial Team
2026-11-21
7 min read

A practical Gutenberg block tutorial covering scaffolding, block.json, attributes, dynamic rendering, testing, accessibility, and release checks.

Custom Gutenberg blocks let you add focused editing features to WordPress without adopting a page builder. This guide presents a reusable workflow for scaffolding, registering, styling, testing, and maintaining a block, with practical checks for static and dynamic rendering.

Overview

A custom block is a small WordPress feature that editors can insert, configure, and preview in the block editor. It can store its own attributes, provide inspector controls, render different markup in the editor and on the frontend, and work with the site’s existing theme styles.

The most maintainable approach is to treat block development as a product workflow rather than a single code snippet:

  1. Define the content problem and decide whether a block is the right solution.
  2. Scaffold the project with the WordPress-supported build tooling.
  3. Describe the block in block.json.
  4. Build the editor interface and frontend output.
  5. Register the block from a plugin or a dedicated feature plugin.
  6. Test permissions, responsive behavior, accessibility, performance, and deactivation behavior.

A block should normally live in a plugin rather than a theme when the content must remain available after a theme change. A theme can be appropriate when the block is tightly coupled to a particular design system, but the choice should be deliberate. For broader theme work, see this WordPress block theme customization guide.

Choose the right building block

ApproachBest forImportant trade-off
Static blockContent whose saved HTML can be generated in the editorMarkup changes may require deprecations or migration logic
Dynamic blockOutput that depends on current data, permissions, or server-side logicRequires PHP rendering and server-side testing
Block patternReusable layouts made from existing blocksLess suitable for custom controls or complex behavior
ShortcodeLegacy content or simple text-based insertionProvides a weaker editor experience than a block
Synced patternReusable content that should stay coordinated across placementsChanges can affect every location where it is used

Checklist by scenario

Scenario 1: Create a basic static block

  1. Prepare a local site. Use a local WordPress development setup with a disposable database and a version-controlled plugin directory.
  2. Scaffold the block. From the plugins directory, run a create-block command such as npx @wordpress/create-block notice-card. Check the generated package instructions before changing build scripts because tooling options can vary between releases.
  3. Review the files. A typical project contains src/ for source files, build/ for compiled assets, block.json for metadata, a PHP entry file, and package files for dependencies and scripts.
  4. Set metadata. Give the block a stable name, readable title, category, description, and icon. Declare editor and frontend assets through editorScript, style, and, when needed, editorStyle.
  5. Define attributes sparingly. Store content that editors need to change, such as a heading, text value, URL, or selected style. Do not store a value when it can be derived from another attribute.
  6. Build the editor view. Use WordPress components and block-editor controls for text, links, colors, spacing, and alignment. Keep editing controls separate from frontend markup where possible.
  7. Build the save view. Return stable semantic markup from save. Use class names that describe the component rather than its appearance alone.
  8. Compile and activate. Run the project’s documented build command, activate the plugin, insert the block, and confirm that saved content survives a reload.

Scenario 2: Build a dynamic block

Use a dynamic block when the output should reflect changing server-side data, such as a list of posts, a logged-in user’s state, or a value that must be escaped and assembled in PHP. The editor can still use a JavaScript preview, but the frontend output should be generated by a render callback.

In block.json, declare a render file or a server-side render configuration supported by the project structure. A simple PHP registration pattern looks like this:

<?php
add_action( 'init', function () {
    register_block_type( __DIR__ . '/build' );
} );

The render callback should validate and escape output according to its context. Use functions such as esc_html() for plain text, esc_attr() for attributes, and esc_url() for URLs. Query only the data the block needs, and avoid performing expensive queries repeatedly when a cached or simpler approach is sufficient.

Scenario 3: Add block supports

Block supports expose standardized controls for features such as alignment, spacing, colors, typography, and anchor values. Add only the supports your design and markup can honor. Enabling a control without styling or rendering it creates a misleading editor experience.

After enabling a support, verify both editor and frontend behavior. For example, if a block accepts a custom class or spacing value, confirm that the generated markup includes the expected attributes and that the theme does not override them unexpectedly.

Scenario 4: Restrict availability

Some blocks are intended for administrators, editors, or a particular post type only. Register the block normally, then control inserter availability with editor-side logic or server-side filters appropriate to the requirement. Treat permissions as a separate concern from visibility: hiding a block does not replace WordPress capability checks around sensitive data or actions.

Scenario 5: Package the block for release

  1. Commit source files and lockfile changes, but do not rely on an untracked local build.
  2. Run the production build in a clean environment.
  3. Test the compiled plugin on a staging site with the intended WordPress and PHP range.
  4. Confirm that deactivating the plugin leaves understandable fallback content rather than silently deleting saved data.
  5. Document installation, build commands, supported features, and any migration notes.

What to double-check

Block metadata and registration

  • The block name uses a stable namespace and slug.
  • Metadata points to files that exist in the distributed plugin.
  • Editor-only assets are not loaded across the entire public site without a reason.
  • The PHP registration path works when the plugin is installed in a different directory.
  • Text intended for translation uses WordPress internationalization functions.

Attributes and migrations

Ask whether each attribute has a clear source, type, default, and failure state. A saved attribute is part of the block’s content contract. If you change its shape or alter the saved markup, use block deprecations and migration logic rather than assuming old posts will update automatically.

Editor-versus-frontend parity

Preview the block in the editor, on a published page, and in a logged-out browser. Check headings, links, images, spacing, colors, and responsive wrapping. A block can appear correct in the editor while inheriting different styles on the frontend.

Accessibility and security

  • Use semantic elements and a logical heading level.
  • Provide accessible names for buttons, links, and interactive controls.
  • Do not use placeholder text as the only label.
  • Escape dynamic output and validate values before using them.
  • Ensure keyboard users can reach and understand every interactive feature.
  • Test contrast and zoom behavior instead of relying only on visual similarity.

Performance and compatibility

Load assets only where they are needed, keep dependencies intentional, and avoid large client-side libraries for small interactions. Test with the site’s active theme, caching configuration, and other plugins. When a block reads external data, define a failure state and review whether a REST API request or server-side render is the better fit. For integrations, this WordPress REST API tutorial provides related workflow guidance.

Common mistakes

  • Putting permanent content in a theme. If the block represents editorial content, a plugin usually gives it a more durable home.
  • Editing compiled files directly. Change source files, then rebuild. Direct edits to build/ are easily lost.
  • Using a dynamic block without planning deactivation. Decide what readers should see if the plugin is disabled, and test that state.
  • Adding too many controls. Every setting increases testing and support work. Start with the smallest useful interface.
  • Relying on editor appearance as proof. Review published pages at multiple widths and with realistic content.
  • Changing markup without migration logic. Existing posts can show validation warnings when saved HTML no longer matches the block definition.
  • Ignoring the build environment. Record the Node, package, WordPress, and PHP assumptions that matter to the project, and retest after dependency updates.
  • Skipping code review. Check escaping, capability handling, asset loading, naming, and deactivation behavior before release. Use a focused WordPress code review checklist as a final pass.

When to revisit

Revisit this checklist before each production release, after changing block attributes or saved markup, and whenever the project updates WordPress, PHP, build dependencies, or the active theme. It is also worth reviewing before seasonal content cycles when editors may create many new entries using the block.

At minimum, repeat the following checks after a tooling change:

  1. Install dependencies from the lockfile in a clean environment.
  2. Run the documented development and production build commands.
  3. Test insertion, editing, saving, duplication, and removal in the editor.
  4. Open existing content created with an earlier block version.
  5. Check frontend markup, responsive layouts, keyboard access, and logged-out output.
  6. Test activation, deactivation, and reactivation on staging.
  7. Record any changed APIs, supports, migration rules, or minimum platform requirements.

Keep the block small, version its source, and make each release reversible. That workflow turns custom Gutenberg block development from a one-off customization into a maintainable part of a WordPress development course or site build.

Related Topics

#Gutenberg#custom blocks#block editor#block.json#JavaScript#PHP
C

Code Craft Studio Editorial Team

WordPress Development Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.