Libra Web and Marketing Solutions

  • Dustin@Lwam.co
  • M-F 9:30-4:30 EST
Linkedin Facebook Instagram Twitter
Menu

How to Create Custom Gutenberg Blocks for Easy Content Editing

by

How to Create Custom Gutenberg Blocks for Easy Content Editing

Custom Gutenberg blocks give clients intuitive, on-brand editing tools—no shortcodes or messy HTML required. In this guide, we’ll cover Block API fundamentals and walk through building a simple plugin that registers a reusable, styled block. By the end, you’ll have a blueprint for empowering clients with their own content modules.

1. Understanding the Block API Fundamentals

Gutenberg’s Block API revolves around two core functions:

  • registerBlockType(name, settings)
    Tells WordPress about your block’s editor UI (edit) and saved output (save).
  • edit & save components
    • edit: A React component rendered in the editor for live previews.
    • save: A function that returns the static HTML each block outputs on the front end.

Key resources:

2. Setting Up the Plugin Boilerplate

Create a plugin folder (custom-blocks) with a main PHP file to register scripts and styles:

<?php
/**
 * Plugin Name: Custom Gutenberg Blocks
 * Description: Registers a styled alert block for clients.
 * Version:     1.0.0
 * Author:      Your USA-Based Team
 * Text Domain: custom-blocks
 */

defined('ABSPATH') || exit;

// Enqueue block editor assets
function cb_enqueue_block_assets() {
  wp_enqueue_script(
    'cb-editor-script',
    plugins_url('build/index.js', __FILE__),
    ['wp-blocks', 'wp-element', 'wp-editor'],
    filemtime(plugin_dir_path(__FILE__) . 'build/index.js')
  );
  wp_enqueue_style(
    'cb-editor-style',
    plugins_url('build/editor.css', __FILE__),
    [],
    filemtime(plugin_dir_path(__FILE__) . 'build/editor.css')
  );
  wp_enqueue_style(
    'cb-frontend-style',
    plugins_url('build/style.css', __FILE__),
    [],
    filemtime(plugin_dir_path(__FILE__) . 'build/style.css')
  );
}
add_action('enqueue_block_assets', 'cb_enqueue_block_assets');

This boilerplate hooks your compiled JavaScript and CSS into both the editor and front end.

3. Registering a Reusable Styled Block

In src/index.js, use the Block API to define an “Alert Box” block:

import { registerBlockType } from '@wordpress/blocks';
import { RichText } from '@wordpress/block-editor';

registerBlockType('custom/alert-box', {
  title: 'Alert Box',
  icon: 'warning',
  category: 'widgets',
  attributes: {
    content: { type: 'string', source: 'html', selector: 'p' }
  },
  edit({ attributes, setAttributes }) {
    return (
      <RichText
        tagName="p"
        className="cb-alert-box"
        placeholder="Enter alert text…"
        value={attributes.content}
        onChange={content => setAttributes({ content })}
      />
    );
  },
  save({ attributes }) {
    return (
      <p className="cb-alert-box">{attributes.content}</p>
    );
  }
});

Compile your block with a tool like webpack or @wordpress/scripts. This registerBlockType call creates an editor placeholder that saves a styled <p> tag.

4. Enqueueing Editor and Frontend Assets

Your custom block needs both editor-only and frontend CSS:

  • editor.css for styling the block canvas (e.g., background color, border).
  • style.css for the live site styles (matching your theme’s design tokens).

Selective loading ensures assets appear only when blocks are present—boosting performance and Core Web Vitals scores. Learn more about our approach in our custom plugin development services.

5. Advanced Customization & Best Practices

  • Block Variations
    Predefine style presets (e.g., “Warning,” “Success,” “Info”) so clients can switch colors without editing CSS.
  • Dynamic Blocks
    Use render_callback in PHP to generate blocks server-side—ideal for blocks that pull live data (events, testimonials).
  • Internationalization
    Wrap translatable strings in __() and load your plugin textdomain for multilingual support.
  • Version Control & Testing
    Store your plugin in Git, use PHPUnit for unit tests, and follow coding standards from the WordPress Handbook.

Ready to Empower Your Clients with Custom Blocks?

Reusable, styled Gutenberg blocks simplify content editing and maintain brand consistency. Our USA-based team specializes in building bespoke WordPress plugins—complete with custom blocks tailored to your workflow.

Schedule a free consultation on our Custom Plugin Development page:
https://lwam.co/wordpress-plugin-development-services/

References

  1. WordPress Block Editor Handbook: https://developer.wordpress.org/block-editor/
  2. MDN Web Docs – JavaScript Modules: https://developer.mozilla.org/docs/Web/JavaScript/Guide/Modules

Let's Get Started!