Creating a WordPress Custom Block: Simple Header

The WordPress Block Editor, commonly known as Gutenberg, has revolutionized content creation in WordPress by introducing a flexible, block-based system powered by React. While it includes a rich set of built-in blocks, custom needs such as specific layout control, branding, or reusable content patterns often require more than what’s available by default.

To address this, we developed a WordPress custom block called “Simple Header”. This block was created to provide enhanced control over the layout and styling of header elements — including a title, header, and subtitle — all customizable directly within the editor.

This documentation walks you through:

• Why we created a custom block
• The challenges it solves
• Step-by-step development process
• Project structure and code
• Deployment and usage

The Need for a WordPress Custom Block

Although Gutenberg offers many built-in blocks in WordPress, we encountered limitations when trying to achieve a specific design and reuse pattern. Here are the main motivations for creating our custom block:

• Custom Layouts: We needed the ability to display a title, header, and subtitle in a specific design layout that wasn’t achievable with default blocks.
• Better Control: We wanted to use custom attributes, placeholder texts, and control over the rendered HTML tags.
• Reusable Content: The same header block needed to be easily reused across multiple pages while maintaining consistent design and editing flexibility.

Project Structure

Here is the folder and file structure of the custom block:

my-simple-header-block/
├── block.json
├── build/
│   └── index.js
├── src/
│   └── edit.js
│   └── index.js
├── style.css
└── plugin.php

Block Configuration: block.json

This JSON file defines the basic settings and metadata for the block:

{
  "apiVersion": 2,
  "name": "sreyas/simple-header",
  "title": "Simple Header",
  "category": "widgets",
  "icon": "heading",
  "description": "A simple custom header block with title, header, and subtitle.",
  "attributes": {
    "title": {
      "type": "string",
      "source": "html",
      "selector": "h1"
    },
    "header": {
      "type": "string",
      "source": "html",
      "selector": "h2"
    },
    "subtitle": {
      "type": "string",
      "source": "html",
      "selector": "h3"
    }
  },
  "editorScript": "file:./build/index.js"
}

Block Registration and Code: src/index.js

import { registerBlockType } from '@wordpress/blocks';
import { RichText, useBlockProps } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';

registerBlockType('sreyas/simple-header', {
  edit({ attributes, setAttributes }) {
    const { title, header, subtitle } = attributes;
    const blockProps = useBlockProps();

    return (
      <div {...blockProps}>
        <RichText
          tagName="h1"
          value={title}
          onChange={(value) => setAttributes({ title: value })}
          placeholder={__('Enter title', 'simple-header')}
        />
        <RichText
          tagName="h2"
          value={header}
          onChange={(value) => setAttributes({ header: value })}
          placeholder={__('Enter header', 'simple-header')}
        />
        <RichText
          tagName="h3"
          value={subtitle}
          onChange={(value) => setAttributes({ subtitle: value })}
          placeholder={__('Enter subtitle', 'simple-header')}
        />
      </div>
    );
  },
  save({ attributes }) {
    const { title, header, subtitle } = attributes;
    const blockProps = useBlockProps.save();
        return (
      <div {...blockProps}>
        <h1>{title}</h1>
        <h2>{header}</h2>
        <h3>{subtitle}</h3>
      </div>
    );
  }
});

Enqueueing the Plugin Script: plugin.php

This file is used to register and enqueue the block assets in WordPress.

<?php
/** * Plugin Name: Simple Header Block */
function sreyas_simple_header_block_register() {
    wp_register_script(
        'sreyas-simple-header',
        plugins_url('build/index.js', __FILE__),
        array('wp-blocks', 'wp-editor', 'wp-element', 'wp-i18n', 'wp-components'),
        filemtime(plugin_dir_path(__FILE__) . 'build/index.js')
    );
    register_block_type('sreyas/simple-header', array(
        'editor_script' => 'sreyas-simple-header',
    ));
}
add_action('init', 'sreyas_simple_header_block_register');

Styling the Block: style.css

You can add CSS to style the block both in the editor and on the frontend:

.wp-block-sreyas-simple-header h1,
.wp-block-sreyas-simple-header h2,
.wp-block-sreyas-simple-header h3 {
  margin: 0;
  padding: 0.5em 0;
}

Include the style using style or editorStyle in your block.json or enqueue it via PHP.

Building the Block

Use a tool like @wordpress/scripts to build the block:

npm install @wordpress/scripts –save-dev

Add this to your package.json:

"scripts": {  "build": "wp-scripts build",  
              "start": "wp-scripts start"}

Then run:  

npm run build

Deployment & Usage

1. Place the my-simple-header-block folder in your WordPress wp-content/plugins/ directory.
   
2. Activate the plugin from the WordPress dashboard.
   
3. Open the Block Editor in any page or post and insert the “Simple Header” block.
   
4. Enter your title, header, and subtitle — it will render exactly as you designed it.

Conclusion

The “Simple Header” block is a practical example of how custom Gutenberg blocks can enhance WordPress content creation. By building a block that fits specific layout and usability needs, we were able to provide content editors with a reusable and user-friendly solution.