Create a custom Gutenberg block from scratch

Custom blocks are how you extend the WordPress editor with your own building pieces. The tooling has settled down a lot, and a modern block is a tidy little package once you have seen its parts. Here is the shape of one.

The pieces of a block

A block is three things working together.

• block.json describes the block: its name, title, category, and attributes.
• An edit function renders the block in the editor, using React.
• A save function returns the markup stored in the post.

Register the whole thing and WordPress wires it into the inserter.

Scaffold and register

The official tooling scaffolds a block for you, which saves fighting the build setup. Once you have the files, registration is one call on the server:

add_action( 'init', function () {
    register_block_type( __DIR__ . '/build/my-block' );
} );

Pointing at the folder with block.json lets WordPress read everything it needs from there.

Store data with attributes

Attributes are how a block remembers its content and settings. Define them in block.json:

"attributes": {
  "message": { "type": "string", "default": "" }
}

Then read and write them in edit:

export default function Edit({ attributes, setAttributes }) {
  return (
    <RichText
      value={attributes.message}
      onChange={(message) => setAttributes({ message })}
    />
  );
}

The save function returns the same content as static markup, so the editor view and the stored output agree.

Where to grow it

Once the basics work, the editor's component library opens up. Add an InspectorControls sidebar for settings, use BlockControls for a toolbar, and pull in ready-made components for colours, spacing, and alignment instead of building your own.

The advice that saves time

Start with the smallest block that does one thing, and get it saving and reloading cleanly before adding controls. Most block headaches are validation errors from edit and save drifting apart, so keep them in step from the start. A small, correct block is a far better base to build on than an ambitious one that will not save.