Creating Custom Blocks with registerBlockType

Contents

Creating Custom Blocks with registerBlockType

WordPress’s block editor (Gutenberg) revolutionizes content creation by providing modular, reusable components. At the heart of this system lies registerBlockType, a JavaScript function that empowers developers to define unique blocks tailored to any use case. This article dives deep into the concepts, patterns, and best practices you need to build robust custom blocks.

1. Why registerBlockType

Declarative API: Define your block’s metadata and behavior in one place.
Extensibility: Hook into rich editing interfaces (InspectorControls, InnerBlocks).
Reusability: Share blocks across projects or publish as plugins.

2. Prerequisites and Environment

WordPress 5.0 with Gutenberg enabled (core or plugin).
Node.js npm for build tools (WordPress Dev Setup).
Familiarity with ESNext (import/export, JSX) – see MDN JS Reference.

3. Basic Syntax

wp.blocks.registerBlockType( my-plugin/my-block, {
nbspnbsptitle: My Block,
nbspnbspicon: smiley,
nbspnbspcategory: layout,
nbspnbspattributes: {
nbspnbspnbspnbspcontent: { type: string, default: }
nbspnbsp},
nbspnbspedit: EditComponent,
nbspnbspsave: SaveComponent,
} )

3.1 Arguments at a Glance

Option	Description
name	Unique namespace/name identifier.
title	Translatable display label.
icon	Dashicon or custom element.
category	Block category slug.
attributes	Data schema extracted from markup.
edit	Component rendering in the editor.
save	Component rendering on the front end.

4. Handling Attributes

Attributes map JSON representation to block markup. Common source types include:

text: Plain text content.
html: Inner HTML of a selector.
attribute: HTML attribute value.

Example:

attributes: {
nbspnbspheading: {
nbspnbspnbspnbsptype: string,
nbspnbspnbspnbspsource: text,
nbspnbspnbspnbspselector: h2,
nbspnbsp},
}

5. Writing the edit Function

The edit component defines the interactive interface. Use InspectorControls, RichText and other Gutenberg components.

import { __ } from @wordpress/i18n
import { RichText, InspectorControls } from @wordpress/block-editor
import { PanelBody, TextControl } from @wordpress/components

function EditComponent( props ) {
nbspnbspconst { attributes, setAttributes } = props
nbspnbspreturn (
nbspnbspnbspnbspltdivgt
nbspnbspnbspnbspltInspectorControlsgt
nbspnbspnbspnbspnbspnbspltPanelBody title={ __( Settings, my-plugin ) }gt
nbspnbspnbspnbspnbspnbspnbspnbspltTextControl
nbspnbspnbspnbspnbspnbspnbspnbspnbspnbsplabel={ __( Subtitle, my-plugin ) }
nbspnbspnbspnbspnbspnbspnbspnbspnbspnbspvalue={ attributes.subtitle }
nbspnbspnbspnbspnbspnbspnbspnbspnbspnbsponChange={ ( val ) =gt setAttributes( { subtitle: val } ) }
nbspnbspnbspnbspnbspnbspnbspnbsp/gt
nbspnbspnbspnbspnbspnbsplt/PanelBodygt
nbspnbspnbspnbsplt/InspectorControlsgt
nbspnbspnbspnbspltRichText
nbspnbspnbspnbspnbspnbsptagName=h2
nbspnbspnbspnbspnbspnbspvalue={ attributes.heading }
nbspnbspnbspnbspnbspnbsponChange={ ( val ) =gt setAttributes( { heading: val } ) }
nbspnbspnbspnbsp/gt
nbspnbspnbspnbsplt/divgt
nbspnbsp)
}

6. Defining save Output

Output is static HTML. Mirror the structure of edit and use RichText.Content when necessary.

function SaveComponent( props ) {
nbspnbspconst { attributes } = props
nbspnbspreturn (
nbspnbspnbspnbspltdiv className=my-block-wrappergt
nbspnbspnbspnbspnbspnbspltRichText.Content tagName=h2 value={ attributes.heading } /gt
nbspnbspnbspnbspnbspnbspltpgt{ attributes.subtitle }lt/pgt
nbspnbspnbspnbsplt/divgt
nbspnbsp)
}

7. Advanced Patterns

InnerBlocks: Nest other blocks (template, allowedBlocks).
Block Variations: Preconfigure styles or attributes (Variations API).
Transforms: Convert between block types programmatically.
Dynamic Blocks: Render PHP output at runtime with render_callback.

8. Registration in PHP

Enqueue the generated scripts and styles, then register the block via register_block_type. Example:

function my_plugin_register_block() {
nbspnbspwp_register_script(
nbspnbspnbspnbspmy-block-editor,
nbspnbspnbspnbspplugins_url( build/index.js, __FILE__ ),
nbspnbspnbspnbsparray( wp-blocks, wp-element, wp-i18n ),
nbspnbspnbspnbspfilemtime( plugin_dir_path( __FILE__ ) . build/index.js
nbspnbsp)
nbspnbsp)
nbspnbspregister_block_type( my-plugin/my-block, array(
nbspnbspnbspnbspeditor_script =gt my-block-editor,
nbspnbspnbspnbspstyle =gt my-block-style,
nbspnbsp) )
}
add_action( init, my_plugin_register_block )

9. Best Practices

Unique Namespaces: Prevent conflicts by prefixing with plugin or vendor name.
Internationalization: Wrap strings with __() and load textdomain (i18n Handbook).
Security: Escape output in PHP (esc_html, wp_kses_post).
Performance: Load only necessary dependencies split editor and front-end styles.
Documentation: Provide clear README, examples, and inline code comments.

10. Tooling and Scaffolding

@wordpress/create-block: Official scaffolding tool (WP-CLI Scaffold).
ESLint Prettier: Enforce code quality.
TypeScript: for stronger type checks in complex blocks.

Conclusion

Mastering registerBlockType unlocks the full potential of Gutenberg. By following this guide—structuring metadata, handling attributes, crafting intuitive edit/save components, and adhering to best practices—you’ll create maintainable, performant, and user-friendly blocks. For further reading, visit the official Block API documentation and explore real-world examples in the WordPress Plugin Directory.

Acepto donaciones de BAT's mediante el navegador Brave 🙂

Creating Custom Blocks with registerBlockType