Custom Gutenberg Blocks Development for WordPress

Developing Custom Gutenberg Blocks for WordPress

Gutenberg replaced TinyMCE as the primary WordPress editor in version 5.0. Custom blocks are React components that render both in the editor and on the frontend. They give editors visual control over structured content without needing to know HTML. Development of one medium-complexity block takes 2–4 days.

Block Registration

The modern approach uses block.json + JavaScript/PHP:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/project-card",
  "version": "1.0.0",
  "title": "Project Card",
  "category": "common",
  "icon": "portfolio",
  "description": "Displays a portfolio project card with image and description",
  "supports": {
    "html": false,
    "align": ["wide", "full"],
    "color": { "background": true, "text": true }
  },
  "attributes": {
    "projectId": { "type": "number" },
    "showDescription": { "type": "boolean", "default": true },
    "imageSize": { "type": "string", "default": "large" }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./editor.css",
  "style": "file:./style.css"
}

PHP registration:

add_action('init', function () {
    register_block_type(__DIR__ . '/blocks/project-card');
});

JavaScript: edit and save

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InspectorControls, MediaUpload } from '@wordpress/block-editor';
import { PanelBody, ToggleControl, SelectControl, Button } from '@wordpress/components';
import { useSelect } from '@wordpress/data';

registerBlockType('my-plugin/project-card', {
  edit: ({ attributes, setAttributes }) => {
    const { projectId, showDescription, imageSize } = attributes;
    const blockProps = useBlockProps({ className: 'project-card-editor' });

    const projects = useSelect(select =>
      select('core').getEntityRecords('postType', 'project', { per_page: 50 })
    );

    const projectOptions = projects
      ? [{ label: '— select project —', value: 0 }, ...projects.map(p => ({ label: p.title.rendered, value: p.id }))]
      : [{ label: 'Loading...', value: 0 }];

    return (
      <>
        <InspectorControls>
          <PanelBody title="Block Settings">
            <SelectControl
              label="Project"
              value={projectId}
              options={projectOptions}
              onChange={v => setAttributes({ projectId: Number(v) })}
            />
            <ToggleControl
              label="Show description"
              checked={showDescription}
              onChange={v => setAttributes({ showDescription: v })}
            />
            <SelectControl
              label="Image size"
              value={imageSize}
              options={[
                { label: 'Thumbnail', value: 'thumbnail' },
                { label: 'Medium', value: 'medium' },
                { label: 'Large', value: 'large' },
              ]}
              onChange={v => setAttributes({ imageSize: v })}
            />
          </PanelBody>
        </InspectorControls>
        <div {...blockProps}>
          {projectId
            ? <ProjectCardPreview projectId={projectId} showDescription={showDescription} />
            : <p>Select a project in the panel on the right</p>
          }
        </div>
      </>
    );
  },

  save: () => null, // dynamic block — render via PHP
});

save: () => null means the block is dynamic—content is rendered by PHP when the page is requested. This is preferable for blocks whose data changes (posts from the database).

PHP Rendering of Dynamic Block

register_block_type(__DIR__ . '/blocks/project-card', [
    'render_callback' => 'my_plugin_render_project_card',
]);

function my_plugin_render_project_card(array $attributes): string {
    $project_id      = absint($attributes['projectId'] ?? 0);
    $show_desc       = (bool) ($attributes['showDescription'] ?? true);
    $image_size      = sanitize_key($attributes['imageSize'] ?? 'large');

    if (!$project_id) return '';

    $project = get_post($project_id);
    if (!$project || $project->post_status !== 'publish') return '';

    $thumbnail = get_the_post_thumbnail($project_id, $image_size, ['class' => 'project-card__image']);
    $title     = esc_html($project->post_title);
    $permalink = esc_url(get_permalink($project_id));
    $excerpt   = $show_desc ? '<p class="project-card__desc">' . esc_html(get_the_excerpt($project)) . '</p>' : '';

    $wrapper_attributes = get_block_wrapper_attributes(['class' => 'project-card']);

    return "<article {$wrapper_attributes}>
        {$thumbnail}
        <h3 class=\"project-card__title\"><a href=\"{$permalink}\">{$title}</a></h3>
        {$excerpt}
    </article>";
}

get_block_wrapper_attributes() adds classes from supports.color and other attributes that Gutenberg generates automatically.

Block with innerBlocks

Container blocks accept child blocks via InnerBlocks:

import { InnerBlocks } from '@wordpress/block-editor';

const ALLOWED_BLOCKS = ['core/paragraph', 'core/heading', 'my-plugin/cta-button'];
const TEMPLATE = [
  ['core/heading', { level: 3, placeholder: 'Section heading' }],
  ['core/paragraph', { placeholder: 'Description...' }],
  ['my-plugin/cta-button', {}],
];

// In edit:
<InnerBlocks allowedBlocks={ALLOWED_BLOCKS} template={TEMPLATE} templateLock={false} />

// In save:
<InnerBlocks.Content />

Build

Blocks are built via @wordpress/scripts:

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:js": "wp-scripts lint-js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  }
}

wp-scripts is configured for WordPress by default: it knows @wordpress/* as external dependencies, generates asset.php with version hash for proper cache invalidation.

Extending Existing Blocks via Filters

You don't always need a new block—sometimes adding an attribute or panel to an existing one is enough:

import { addFilter } from '@wordpress/hooks';
import { createHigherOrderComponent } from '@wordpress/compose';

// Add "data-section" attribute to any block
addFilter('blocks.registerBlockType', 'my-plugin/add-section-id', (settings) => {
  settings.attributes = {
    ...settings.attributes,
    sectionId: { type: 'string', default: '' },
  };
  return settings;
});

// Add field to InspectorControls
const withSectionIdControl = createHigherOrderComponent(BlockEdit => {
  return (props) => {
    const { attributes, setAttributes } = props;
    return (
      <>
        <BlockEdit {...props} />
        <InspectorControls>
          <PanelBody title="Anchor Link">
            <TextControl
              label="Section ID"
              value={attributes.sectionId}
              onChange={v => setAttributes({ sectionId: v })}
            />
          </PanelBody>
        </InspectorControls>
      </>
    );
  };
}, 'withSectionIdControl');

addFilter('editor.BlockEdit', 'my-plugin/section-id-control', withSectionIdControl);

Typical Timelines

Simple static block with 2–3 attributes: 4–8 hours. Dynamic block with PHP render and settings panel: 1–2 days. Container block with innerBlocks, custom styling, and server-side render: 2–4 days. Set of 5–10 related blocks for design system: from 2 weeks.