How to Create a Custom Gutenberg Block in WordPress (Step-by-Step Guide)

WordPress / By / February 7, 2026
How to create a custom Gutenberg block in WordPress step‑by‑step guide

The Gutenberg block editor (introduced in WordPress 5.0) has become the default way to build content in WordPress. While there are thousands of pre-made blocks from plugins and themes, creating your own custom Gutenberg block gives you complete control — perfect for branded elements, reusable components, or unique functionality that no existing block offers. In 2026, with full-site editing and block themes now standard, custom blocks are more important than ever for agencies, developers, and businesses wanting consistent design across pages.

At Cope Business, we build custom Gutenberg blocks for clients during our technical SEO audit services to improve content consistency, page speed, and user experience without relying on heavy third-party plugins.
This beginner-to-intermediate guide shows you two practical ways to create a custom Gutenberg block in WordPress — using a plugin (easiest) and from scratch with code (most flexible).

Why Create a Custom Gutenberg Block?

  • Brand Consistency — Create reusable elements that match your design system
  • Unique Functionality — Add features no existing block has (e.g., custom pricing tables, testimonials with ratings)
  • Performance — Avoid bloated plugins; only load what you need
  • Reusability — Use the same block across posts, pages, and templates
  • Future-Proof — Block themes and full-site editing make custom blocks more powerful

Method 1: Using a Plugin – Easiest Way (No Code Required)

If you want to create blocks without writing JavaScript/PHP, use a block builder plugin.

Recommended Plugin: Block Lab or Kadence Blocks (Free/Pro)

Best Free Option: Kadence Blocks (free core + Pro)

Steps

  1. Install Kadence Blocks from Plugins > Add New.
  2. Go to Kadence Blocks > Block Library → Enable any starter blocks you like.
  3. For truly custom blocks:
    • Use Kadence Blocks Pro (~$79/year) → Advanced Custom Blocks feature
    • Or use Block Lab (free) + Advanced Custom Fields (ACF) (free/pro)
  4. In ACF → Create a new Field Group → Add fields (text, image, repeater, etc.)
  5. In Block Lab → Create new block → Link to ACF fields → Design template in PHP/HTML
  6. Save → New block appears in Gutenberg inserter.

Alternative: Gutenberg Block Generator (online tool) → Generates code → paste into WPCode.

Pros: No/low code, visual setup, fast.
Cons: Less flexibility than pure code; may add bloat.

Method 2: Creating a Custom Block from Scratch (Code Method – Most Powerful)

This method gives full control and is future-proof for block themes.

Prerequisites

  • Local/staging site (LocalWP or DevKinsta)
  • Node.js & npm installed
  • Basic JavaScript & PHP knowledge
  • Code editor (VS Code)

Step-by-Step: Create a Simple “Call to Action” Block

  • Create Plugin Folder
    • /wp-content/plugins/cope-custom-blocks/Create: cope-custom-blocks.php
PHP<?php /** * Plugin Name: Cope Custom Gutenberg Blocks * Description: Custom blocks for Cope Business sites * Version: 1.0 * Author: Cope Business */ function cope_register_custom_blocks() { if ( ! function_exists( 'register_block_type' ) ) { return; } register_block_type( __DIR__ . '/blocks/call-to-action' ); } add_action( 'init', 'cope_register_custom_blocks' ); function cope_enqueue_block_assets() { wp_enqueue_script( 'cope-blocks-editor', plugins_url( '/blocks/call-to-action/index.js', __FILE__ ), array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor' ), filemtime( plugin_dir_path( __FILE__ ) . 'blocks/call-to-action/index.js' ) ); wp_enqueue_style( 'cope-blocks-style', plugins_url( '/blocks/call-to-action/style.css', __FILE__ ), array(), filemtime( plugin_dir_path( __FILE__ ) . 'blocks/call-to-action/style.css' ) ); } add_action( 'enqueue_block_editor_assets', 'cope_enqueue_block_assets' );
  • Create Block Folder & Files
    • Create folder: /blocks/call-to-action/Add files:
      • block.jsonindex.jseditor.cssstyle.css
    block.json (defines block metadata)
JSON{ "apiVersion": 3, "name": "cope/call-to-action", "title": "Call to Action", "category": "text", "icon": "megaphone", "description": "A custom call to action block", "supports": { "html": false }, "textdomain": "cope-blocks", "editorScript": "file:./index.js", "style": "file:./style.css", "editorStyle": "file:./editor.css", "attributes": { "title": { "type": "string", "default": "Ready to Get Started?" }, "content": { "type": "string", "default": "Contact us today for a free consultation." }, "buttonText": { "type": "string", "default": "Get in Touch" }, "buttonUrl": { "type": "string", "default": "" } } }
  • index.js (editor & save logic)
JavaScriptimport { registerBlockType } from '@wordpress/blocks'; import { TextControl, URLInputButton } from '@wordpress/components'; import { useBlockProps } from '@wordpress/block-editor'; registerBlockType( 'cope/call-to-action', { edit: ( { attributes, setAttributes } ) => { const blockProps = useBlockProps(); return ( <div { ...blockProps }> <TextControl label="Title" value={ attributes.title } onChange={ ( val ) => setAttributes( { title: val } ) } /> <TextControl label="Content" value={ attributes.content } onChange={ ( val ) => setAttributes( { content: val } ) } /> <URLInputButton label="Button URL" url={ attributes.buttonUrl } onChange={ ( url ) => setAttributes( { buttonUrl: url } ) } /> <TextControl label="Button Text" value={ attributes.buttonText } onChange={ ( val ) => setAttributes( { buttonText: val } ) } /> </div> ); }, save: ( { attributes } ) => { const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <h3>{ attributes.title }</h3> <p>{ attributes.content }</p> { attributes.buttonUrl && ( <a href={ attributes.buttonUrl } className="button"> { attributes.buttonText } </a> ) } </div> ); }, } );
  • style.css & editor.css — Add basic styling.
  • Activate Plugin → Go to Plugins → Activate “Cope Custom Gutenberg Blocks”.
  • Test: Add block in editor → “Cope / Call to Action” appears → Customize & save.

Pros: Full control, reusable, no extra plugins. Cons: Requires JavaScript/PHP knowledge; test thoroughly.

Best Practices for Custom Gutenberg Blocks

  • Always use a plugin or child theme — never edit core files.
  • Use @wordpress/scripts for modern block development (npm start/build).
  • Test on mobile, different browsers, and block themes.
  • Keep blocks lightweight — avoid heavy dependencies.
  • Add block styles & variations for flexibility.
  • Use @wordpress/block-editor hooks for best compatibility.

Custom blocks give you branded, reusable elements — great for consistency.

Final Thoughts

Creating a custom Gutenberg block in WordPress lets you add exactly the functionality and design your site needs. Start with a plugin like Kadence Blocks or Block Lab if you want low-code, or build from scratch for maximum control.

Custom blocks future-proof your site for block themes and full-site editing.

Need help creating custom blocks, optimizing your editor, or improving overall site performance? Contact Cope Business for a free technical SEO consultation — we’ll build tailored blocks and solutions to elevate your WordPress experience.

Was this article helpful?
YesNo

Related Posts