Two Ways to Create Custom WordPress Blocks

The WordPress block editor was made the default editor for WordPress in December 2018. Adoption may have been slow at first, but the pace of development has increased exponentially. Today, custom blocks are at the core of extending WordPress. In this article, we’ll cover two ways to create custom blocks: with React and the @wordpress/create-block tool, and with the ACF Blocks feature of Advanced Custom Fields.

What Are WordPress Blocks?
Creating Blocks With React
Creating Blocks With ACF
1. Building an ACF Block
Wrapping Up

What Are WordPress Blocks?

WordPress blocks are components used for creating and editing elements in a WordPress post or page. Native WordPress blocks split into static blocks, rendered in the browser, and dynamic blocks, which are rendered on the server.

Content and markup from static blocks are saved in the post content, and manual edits are required to change the content. Static blocks are written in JavaScript.

Dynamic blocks, as the name implies, can change their content without the manual intervention required by static blocks. For example, a dynamic block could be used to display the site’s name, picking up the name from the site’s settings when the block is rendered. Dynamic blocks use JavaScript to create the editor experience, and PHP to render the front end markup on the server.

ACF Blocks are a custom type of dynamic block. Even when they’re used in the same way as a static WordPress block, they’re rendered by ACF on the server and allow you to use PHP logic.

Creating Blocks With React

The Block Editor Handbook is a great resource when it comes to actually creating blocks, but it may not be the best starting point. Go ahead and dive right in if you have a solid understanding of React and modern JavaScript, but if not, you’ll probably want to go over the React Quick Start tutorial.

WordPress blocks have come a long way since their introduction in WordPress 5.0. There’s even an officially supported tool, @wordpress/create-block, for scaffolding a WordPress plugin that registers a block. The package generates everything you need to get started: PHP, JavaScript, and CSS.

Setting Up Your Dev Environment

The first thing you’ll need is to set up your development environment. The WordPress documentation on block development environments goes into more detail, but basically there are three things you need:

A code editor, such as VS Code
Node.js dev tools
A local WordPress site

We recommend using Local to create your local WordPress install, or wp-env, which is maintained by the WordPress project.

Once you have that in place, you’re ready to create your first block. Open your terminal and navigate to the directory where your local WordPress install stores its plugins. If you’re using Local, this will be something like Local Sites\mywp\app\public\wp-content\plugins. Using wp-env will map any directory you choose to work from as the plugin directory for your site.

Once you’re in the right directory, run the following line:

npx @wordpress/create-block

This calls the package, and then asks you a series of questions to help customize your plugin. The first choice you need to make is if it’s going to be static or dynamic. I want to keep this simple, so I’m going to choose “static.”

Let's customize your WordPress plugin with blocks:
? The template variant to use for this block: static
? The block slug used for identification (also the output folder name): mediummike
? The internal namespace for the block name (something unique for your products): mediummike-basicblock
? The display title for your block: Medium Mike's Basic Block
? The short description for your block (optional): A block that displays a text message.
? The dashicon to make it easier to identify your block (optional): welcome-view-site
? The category name to help users browse and discover your block: widgets
? Do you want to customize the WordPress plugin? Yes
? The home page of the plugin (optional). Unique URL outside of WordPress.org:
? The current version number of the plugin: 0.1.0
? The name of the plugin author (optional). Multiple authors may be listed using commas: Mike Davey
? The short name of the plugin’s license (optional): GPL-2.0-or-later
? A link to the full text of the license (optional): https://www.gnu.org/licenses/gpl-2.0.html
? A custom domain path for the translations (optional):
? A custom update URI for the plugin (optional):

You’ll also need to choose a block slug (which will also be used as the name of the folder) and provide an internal namespace. Some care should be taken here to use a namespace that won’t cause namespace clashes, uses a scalable structure so it can be extended if needed, and only uses lowercase alphanumeric characters or dashes.

Next enter the display title for your block, and provide a short description. You can also choose a dashicon. This is completely optional, but I elected to use welcome-view-site, because it reminds me of the Paranoia roleplaying game.

Tell me I’m wrong.

You must also decide on a category for your block. This won’t provide your block with any functionality, but it helps make it easier to discover.

Alternatively, you can skip the interactive mode and scaffold your plugin with a more complex command:

$ npx @wordpress/create-block@latest [options] [slug]

Using slug triggers quick mode, meaning whatever you put here is used as the block slug, the output folder name for your scaffolded files, and the name of the plugin itself. Using options allows args that change the default configuration.

At this point, you should have a working WordPress plugin installed on your local WordPress site. Pop into your “Plugins” page and confirm that it’s installed. You can also activate it at this stage, but of course it doesn’t do anything yet. To add functionality, we’ll need to dive into the scaffolded files.

Block Plugin File Structure

The scaffolded plugin should have some files in its root, and three subdirectories:

├── yourplugin
├── build
├── node_modules
├── src
├── .editorconfig
├── .gitignore
├── mediummikesbasicblock.php
└── src
    ├── app.js
    ├── models.js
    ├── routes.js
    └── utils
        ├── another.js
        ├── constants.js
        └── index.js

There are two files in the root we’re concerned with here: package.json and a PHP file with the same name as your slug.

The package.json file is where properties and scripts are defined. Your scaffolded block should have one dependency initially:

"devDependencies": {
    "@wordpress/scripts": "26.16.0"

This bundles the tools and configurations you’ll need to build WordPress blocks. You can install other dependencies if you wish, but you get a lot of what you’ll need right here.

The scripts section of package.json defines the commands available to npm run ():

    "scripts": {
        "build": "wp-scripts build",
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
        "packages-update": "wp-scripts packages-update",
        "plugin-zip": "wp-scripts plugin-zip",
        "start": "wp-scripts start"

The main scripts here are build and start. Using npm run build will create a production build with compressed code. This speeds up downloads, but it’s harder to read and debug.

Use npm run start during the development phase to create an uncompressed build of the code and ease the development process. This command also starts a watch process to rebuild the file each time it’s saved.

These scripts need a JavaScript file to build, and default to looking at src/index.js in the scaffolded plugin, and saving the built file to build/index.js.

No matter which build script is used, the block won’t run in the editor if WordPress doesn’t know about it. The PHP template file generated by npx @wordpress/create-block includes an init action to register the block and specify the editor script handle registered from the metadata provided in build/block.json with the editorScript field. When the editor loads, it will load this script and register the block.

/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/reference/functions/register_block_type/
 */
function mediummike_mediummike_block_init() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'mediummike_mediummike_block_init' );

WordPress blocks are essentially JSON objects. The JavaScript that defines that object is located in the src/index.js file.

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';

/**
 * Internal dependencies
 */
import Edit from './edit';
import save from './save';
import metadata from './block.json';


registerBlockType( metadata.name, {
    /**
     * @see ./edit.js
     */
    edit: Edit,

    /**
     * @see ./save.js
     */
    save,
} );

The registerBlockType function is imported from @wordpress/blocks and takes two arguments: a block name and a block configuration object. The block configuration object contains information about the block, such as its title, description, and category.

The src/index.js file is the entry point for the block, and it’s where you’ll define the registerBlockType function and import any necessary dependencies. The scaffolded file will have some dependencies already set up:

import './style.scss';: This lets webpack process any CSS, SASS, and SCSS files referenced in the block, bundling together any files that contain the style keyword. Code used is applied to the block on both the front end of the site and in the editor.
import Edit from './edit';: This imports the edit function for the block, which is defined in the edit.js file. The edit.js file contains the code that will be executed when the user edits the block in the WordPress editor. It typically includes the block’s edit form, which allows the user to set the block’s attributes.
import save from './save';: This imports the save function for the block, which is defined in the save.js file. The save.js file contains the code that will be executed when the user saves the block in the WordPress editor. It typically includes the code that will be executed when the block is saved, such as saving the block’s attributes to the database.
import metadata from './block.json';: This imports the metadata for the block, which is defined in the block.json file.

Block Metadata in block.json

The block.json file contains information about the block, such as its name, title, and description. It also contains information about the block’s attributes, which are the properties that can be set for the block.

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "mediummike-basicblock/mediummike",
    "version": "0.1.0",
    "title": "Medium Mike's Basic Block",
    "category": "widgets",
    "icon": "welcome-view-site",
    "description": "A block that displays a text message.",
    "example": {},
    "supports": {
        "html": false
    },
    "textdomain": "mediummike",
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "style": "file:./style-index.css",
    "viewScript": "file:./view.js"
}

Let’s unpack some of the block metadata and see what it’s doing.

supports: This property defines the features that the block supports. For example, if the block supports align, it means that the block can be aligned to the left, right, or center. If the block supports anchor, it means that the block can be linked to using an anchor tag.
textdomain: This property defines the text domain for the block. The text domain is used to translate the block’s text into different languages.
editorScript: This property defines the JavaScript file that will be used to render the block in the WordPress editor. The file should be located in the src directory of the block.
editorStyle: This property defines the CSS file that will be used to style the block in the WordPress editor. The file should be located in the src directory of the block.
style: This property defines the CSS file that will be used to style the block on the front-end of the website. The file should be located in the src directory of the block.
viewScript: This property defines the JavaScript file that will be used to render the block on the front-end of the website. The file should be located in the src directory of the block.

Setting Block Attributes

Attributes define the block’s properties and behavior. The scaffolded block.json file doesn’t have any attributes to begin with. If you want a block that actually does something, like allow you to edit text, you have to use Gutenberg’s state management system. That’s what the attributes object is. It’s pretty much identical to React’s state management concept, a top-level object that keeps track of properties and what’s changed.

To set attributes in block.json, add a new object called attributes to the file at the same level as the name and title fields. Individual attributes are defined within the object by key-value pairs, with the key naming the attribute and the value providing the definition.

"attributes": {
    "message": {
        "type": "string",
        "source": "text",
        "selector": "div",
        "default": ""
    }
},

Attributes must be defined for each editable part of the block. The example above allows a content editor to add a message that will be displayed when the post is published.

At minimum, the attribute definition must contain either a type, indicating the type of data stored, or an enum with an array of allowed values. It is possible to use type and enum together to first indicate the type of data, and then define it from a set of fixed values.

The source field defines how attribute values are extracted from saved post content. Basically it’s a way to map HTML post markup into a JavaScript form. If you don’t define it, the data will be stored in the comment delimiter. Specifying a selector argument will run it against the block’s matching elements, in this case div.

There is no limit to the number of attributes that can be added. For example, we could add attributes that deal with the post’s images:

"mediaID: {
        "type": "number"
    },
"mediaURL: {
        "type": "string",
        "source": "attribute",
        "selector": "img",
        "attribute": "src"
    },

In some cases, like mediaID above, the type is all you need. The mediaURL in the example above needs more: source: "attribute, to specify that the data is stored in an HTML element attribute, with selector: "img", indicating it should match the img element. Finally, the attribute specified by source must be defined, in this case with src, i.e., the URL associated with the HTML src element.

Edit and Save

The attributes set in src/block.json are passed to the edit() and save() functions defined in src/edit.js and src/edit.js, along with additional parameters. The src/edit.js file also needs to have the setAttributes function to update the attributes.

The src/edit.js file also includes component imports to build and modify the block’s UI. For example, you can add a button component by importing an existing component from `@wordpress/components:

import { Button } from '@wordpress/components';

export default function MyButton() {
    return <Button>Clickety-click!</Button>;
}

One of the more commonly used components is TextControl, useful for allowing users to enter and edit short amounts of text. For longer text, TextareaControl is probably a better option.

Code comments on the scaffolded edit.js and save.js files are pretty thorough, with a lot of hints about how to modify the files. Here’s the scaffolded edit.js with no modifications:

/**
 * Retrieves the translation of text.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
 */
import { __ } from '@wordpress/i18n';

/**
 * React hook that is used to mark the block wrapper element.
 * It provides all the necessary props like the class name.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
 */
import { useBlockProps } from '@wordpress/block-editor';

/**
 * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
 * Those files can contain any CSS code that gets applied to the editor.
 *
 * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
 */
import './editor.scss';

/**
 * The edit function describes the structure of your block in the context of the
 * editor. This represents what the editor will render when the block is used.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
 *
 * @return {Element} Element to render.
 */
export default function Edit() {
    return (
        <p { ...useBlockProps() }>
            { __(
                'Medium Mike&#39;s Basic Block – hello from the editor!',
                'mediummike'
            ) }
        </p>
    )
}

If you’re familiar with React’s render() function, it’s pretty similar. You essentially specify a return statement that has your JSX in it. For example, here’s how to modify edit.js so it imports TextControl and the message attribute defined earlier:

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
    return (
        <div { ...useBlockProps() }>
            <TextControl
                label={ __( 'Message', 'yourblockname' ) }
                value={ attributes.message }
                onChange={ ( val ) => setAttributes( { message: val } ) }
            />
        </div>
    );
}

The onChange attribute is where the onChange() function is assigned. This is important, as it’s how block attributes are updated.

The save.js file is usually simpler than edit.js, with fewer imports:

/**
 * React hook that is used to mark the block wrapper element.
 * It provides all the necessary props like the class name.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
 */
import { useBlockProps } from '@wordpress/block-editor';

/**
 * The save function defines the way in which the different attributes should
 * be combined into the final markup, which is then serialized by the block
 * editor into `post_content`.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#save
 *
 * @return {Element} Element to render.
 */
export default function save() {
    return (
        <p { ...useBlockProps.save() }>
            { 'Medium Mike&#39;s Basic Block – hello from the saved content!' }
        </p>
    );
}

To match the modified edit.js file above that imports TextControl and the message attribute, the save.js file would look like this:

import { useBlockProps } from '@wordpress/block-editor';
export default function save( { attributes } ) {
    const blockProps = useBlockProps.save();
    return <div { ...blockProps }>{ attributes.message }</div>;
}

The block now has some functionality. It doesn’t do much, but it meets the requirements of being a minimally functional block that can be inserted in the WordPress block editor.

A World of JavaScript

Blocks are made almost entirely in JavaScript. WordPress uses two actions, enqueue_block_assets and enqueue_block_editor_assets, to let you include your JavaScript and stylesheets to be used with the block editor. All you really need to do PHP-wise is enqueue your JavaScript and CSS files and call register_block_type() with each asset’s handle.

Long story short, adding more functionality to your WordPress blocks requires sharp JavaScript skills, in particular the ESNext syntax and React. These skills are more common among WordPress developers than they were a few years ago, but there are still a lot of folks who are more comfortable (and faster!) doing as much as possible in PHP.

Creating Blocks With ACF

It’s a lot of work to create truly custom WordPress blocks, even with the scaffold commands and thorough documentation. ACF Blocks lets you create custom WordPress blocks, but in a PHP framework.

Both WordPress core blocks and ACF Blocks register their properties in block.json, but ACF Blocks also have a PHP template for rendering the block, and a CSS file to apply any unique styling. Alternatively, you can skip the CSS file if you just want your ACF Block to inherit styles from your theme.

An ACF Block will often have an associated ACF field group, allowing it to pull data from the fields. However, it is perfectly feasible to create an ACF Block that does not use any ACF fields.

The configuration keys used in ACF Blocks are largely the same as the ones used in WordPress core blocks, including the use of camelCase. The primary difference is the addition of the acf configuration key, which controls the block’s display mode and template used for rendering.

Building an ACF Block

Just like creating native WordPress blocks, the first consideration is your development environment. You’ll need a copy of ACF PRO, as ACF Blocks is a premium feature that isn’t available in the free version of ACF, and a WordPress site where you have access to the wp-content directory. We recommend spinning up a site in Local so you can experiment in complete safety.

With those in place, the process of creating an ACF Block can be broken down into six steps:

Create a child theme or plugin to hold your ACF Blocks
Create a functions.php file
Register properties in block.json
Associate the block with an existing field group, or create a new one (optional)
Create the template
Create the stylesheet (optional)

ACF’s Create Your First Block tutorial goes over these steps in detail, using a basic testimonial block as an example.

The tutorial shows every step of the process needed to create the testimonial block, from creating a child theme to applying styling. The block populates with data drawn from associated ACF fields, including a Text Area field to hold the quote, Text fields to enter the person’s name and role, an Image field, and Color Picker fields to set background and text colors.

Compared to creating native WordPress blocks, building ACF Blocks is much simpler, especially if you already know your way around WordPress and PHP templates. The process to populate the block is likely already familiar to your content editors: choose the ACF Block in the WordPress block inserter, fill in the ACF fields, make any desired adjustments, and it’s ready to publish:

Later tutorials from ACF build on the basic concepts, showing how to use InnerBlocks, block locking, and block context with your ACF Blocks.

Once you’ve got the basics down, check out how to build a slider block with ACF Blocks:

Wrapping Up

Custom blocks help expand your options when building WordPress sites, allowing content editors to expand their scope and creativity while staying within carefully designed parameters.

As long as the blocks you build serve their purpose, there’s no wrong way to create WordPress blocks. With that said, creating fully customized ACF Blocks has a much shorter learning curve, and allows you to easily draw in data from existing or new ACF field groups.

Have you created custom blocks with React, ACF Blocks, or both? Did you have a strong preference for one or the other? Let us know in the comments.

This entry was posted in WP Migrate DB Pro, Code and tagged Plugin, WordPress Core, WordPress Development, Theme, JavaScript, Gutenberg, ACF, Blocks.

.replybox-fallback, .replybox-fallback ul { list-style: none; }

bigbassroller@gmail.com says:

March 6, 2018 at 9:29 am

Thanks for the timely article. I feel like theres multiple ways to build wp sites now. The regular way, wp-json and in the future the gutenberg way. Either way, I think the future looks strong for WordPress.

Per Sturesson says:

March 7, 2018 at 12:51 am

Thanks for another great article! Being a little more experienced than the usual client I’m not fully seeing the potential of Gutenberg. While I understand it’s easier when you get a representable presentation on how your content will look when published, I seem to lean towards decoupling the CMS from the frontend and rather build an app that consumes data from the CMS as it gives me more freedom in the end.

Peter Tasker says:

March 8, 2018 at 7:19 am

Yep, you’re 100% correct. I think the REST API is probably the real future of WordPress. But from what I can tell focusing on the editor is to compete with other platforms (Wix, Squarespace) that have better editors (allegedly).

Reply
- Adam Patterson says:
  
  March 8, 2018 at 8:07 am
  
  They should test it our on WordPress.com then 🙂
  
  Reply
- SunShine says:
  
  May 6, 2020 at 6:32 pm
  
  So you’re thinking headless is the way to go, eh?
  
  Reply

Adam Patterson says:

March 7, 2018 at 4:39 pm

The one off putting thing to me, is that the blocks are made using Javascript. Specifically React with Redux. In theory it’s possible to have custom blocks calling and conflicting with Redux core / new actions. Possibly some how extending ( can you? ) and managing changes as the block developer sees fit. It also seems strange to me that the ultimate end product of this editor is HTML entered into a database ( while I have not looked to confirm this ). Would it have not been more straight forward and fit the WordPress mold a little more to have used HTML blocks with special data attributes that could reference functionality? This could allow the editor to be a separate thing from the blocks. Like the only reason the blocks are in React is so that they work with the Editor. Not so that they work WordPress themes. How does this impact the WordPress API? What if you were already building a theme that was React powered and uses the WordPress API. It’s possible that these blocks now are very limiting to what you could have done if you stored this data as an object and rendered it out into the HTML template you already had OR consume it as a natural object from the API. Kind of like using ACF.

Peter Tasker says:

March 8, 2018 at 7:17 am

As far as I know, React and Redux are just used with the new editing experience. The front-end will continue to be the same as it always has. I think the bigger issue is that now Gutenberg creates a real WYSIWYG editing experience people may be jarred when looking at the front-end if it looks drastically different then what they’ve created in wp-admin. I hear you with the ACF API, I think it would’ve been awesome if a new API was created so that we could also query and assemble the front-end a bit easier!

Reply
- Adam Patterson says:
  
  March 8, 2018 at 8:06 am
  
  If it becomes part of Core, I can see there being a "classic" plugin created 🙂 I am conflicted really. It seems like the benefits are a-lot stronger for designers, and maybe even the theme industry. But not as convincing for developers. I am also curious to see how any preexisting visual editor theme will work.
  
  Reply
  - mikelking says:
    
    March 9, 2018 at 5:05 am
    
    There already is a classic editor plugin ready to go for 5.0. Just in case you’re feeling a little editorially retro… https://wordpress.org/plugins/classic-editor/
    
    Reply
- Adam Patterson says:
  
  July 7, 2020 at 12:45 pm
  
  Circling back 2 years later 🙂 Here is another problem that I came across, It might be very specific but for my use cases I have still stuck with ACF and custom layouts because the sites I build are not suited to the Gutenberg Editor. That said, I have my own blog where I wanted to add a Mailchimp subscription form. And would you look at that, Jetpack has a Mailchimp block! Presto… Oh wait, ALL of the elements are inside of paragraph tags… I can change the layout by targeting child paragraph tags but to me that sucks. I wish there was a way to modify the layout from your template, since the HTML is stored in the database it wouldn’t have any impact on performance.
  
  Reply

Rob Mehew says:

March 9, 2018 at 5:37 am

I am excited but nervous about learning to create my own Guten Blocks, am I being silly about not learning it yet incase the framework changes from React? Is that likely even after the license changes from Facebook. Should I just dive in and create some blocks? – I have already created a basic block that does nothing, but I guess I am just wondering what is the best direction to focus my learning with regards to the Block Editor.

Peter Tasker says:

March 9, 2018 at 6:30 am

I don’t think there’s anything to worry about with the Facebook licensing stuff now. That’s largely been resolved as they’ve changed their patent clause, which is what everyone had issue with. https://code.facebook.com/posts/300798627056246/relicensing-react-jest-flow-and-immutable-js/ I’d start with the Gutenberg documentation, they have some basics on how to create blocks, but it’s an evolving thing.

Reply
- Rob Mehew says:
  
  March 9, 2018 at 7:56 am
  
  Ah awesome ok, I only ask because on this post: https://ma.tt/2017/09/facebook-dropping-patent-clause/ Matt says that the React choice is a decision still be made. Thanks I’ll take a look! 🙂
  
  Reply

jvanpelt says:

July 16, 2018 at 9:09 am

Nice article! I’ve been contributing to the development of Gutenberg and the effort that the WP team have put into it has been huge, wether one agrees with the directions they’re taking or not it’s amazing how much has been done in such a short time. Something I wanted to point out is that block attributes should be defined "on the server" so PHP is aware of them, in fact you probably don’t need to return anything in the save() method since you can render the block for the frontend server-side, eg the latest post block: https://github.com/WordPress/gutenberg/blob/e31c87b3df0824f9edff2f9904292c7f370de3ec/blocks/library/latest-posts/index.php I don’t think this is documented yet and like you said it’s most likely subject to change but just felt worth to point out. Another thing I came across is that you can’t just use another ‘default’ block in your own custom block. Not every built-in block has an API or is exposed as a public class. Not sure what you meant about this, do you mean using it in a way different than: import { SomeBlock } from ‘@wordpress/blocks’;

Danny van Kooten says:

August 20, 2018 at 1:15 pm

Thanks for the article, I really enjoyed it. The "modified externally" thing is a so annoying. You wrote this in March – did you come up with a workaround or a way to update blocks?

Peter Tasker says:

August 27, 2018 at 10:02 am

TBH I haven’t revised this code at all since I wrote the article! A lot has changed in React and Gutenberg since I wrote it, so I think it’s due for an update.

Reply

Wouter de Vries says:

August 27, 2018 at 2:46 am

Thanks for this tutorial, but I’m getting an error in the editor "ReferenceError: sortOutCSSClasses is not defined". Any ideas how to fix this?

riw777 says:

December 8, 2018 at 5:40 am

It’s all well and good to force everyone to use react, but not all of us are full on developers. It seems, to me, that what wordpress is doing here is cleanly separating content producers from developers. This may be great for the developer community, or it could, ultimately, kill wordpress, as there is no way to ‘tinker’ with the content any longer. Doing anything custom with a post, for someone who is not a full time developer, now requires going to some marketplace and hiring someone, rather than playing with some css and html to make it look the way you want. Is this a good thing for the ‘web, or a bad one? IMHO, a bad one. It closes off the ability to develop custom content, relegating this role solely to full time developers and shutting the "tinker" market out. Tthe entire look and feel of wordpress sites will become even more generic and uniform over time. Experimenting will be expensive because it must be done by a professional, and hence it will not be done. Overall, I think wordpress just shot themselves in the foot. They will gain a million new users and build a larger development market in the short term, but in the log term they have ossified their product, making it something anyone can publish content with, but only a professional can tinker with. In the longer term, wordpress will crash because all the vitality of individuals experimenting and building unique things will be sucked out. WordPress is becoming the McDonald’s or Walmart of the web publishing world. Successful after a sense, but ultimately representing a huge dead zone of corporate sameness. I’m certain this is all great for you as a professional wordpress developer, but for the overall community, it’s a disaster.

Graeme says:

December 18, 2018 at 5:24 am

I dont think it has to be used… and Im sure themes will be built as they were before. People will continue to use flexible content (ACF) for example… I personally find it hard to picture a client who wants a professional website going to an agency and saying design me some blocks please. It’s just not practical, and whats available isn’t good enough to compete with the designed/developed market.

Reply

aezaz shaikh says:

January 17, 2019 at 9:31 am

Yeah, API change is a pain, I’m also tired of this

aezaz shaikh says:

March 11, 2019 at 1:35 am

This is such an great post about custom gutenberg block. I love everything about gutenberg blocks as it helps to add stunning animations to make your website looks great.

Simon H Lee says:

January 17, 2020 at 7:30 pm

If I remember correctly, Project Gutenberg was in large part, developed to enhance the WordPress.com publishing experience for non-coders. I think Automattic understands and wants to deliver products to coders and non-coders, so Gutenberg will continue to evolve to compete with SquareSpace, Wix, etc. I don’t think this will hurt WP at all. If anything, it’s a good business move to clearly differentiate WordPress.org for coders, and WordPress.com for non-coders.

leoloso says:

April 22, 2020 at 12:48 pm

There is now an official scaffolding package too: @wordpress/create-block, which also works for creating single-block plugins. And it supports hot reloading! (well, sort of, it’s not very fast to reload… but it is still triggered automatically when making a change to the source files). Here I explain how to set it up.

Peter Tasker says:

April 22, 2020 at 1:30 pm

Hey, that’s cool! I didn’t know about @wordpress/create-block before I wrote this article, nice tip.

Reply

Pere Cat says:

April 23, 2020 at 11:11 pm

Nice article buddy! But in fact, WordPress blocks s*ucks… More than 15% of the WordPress sites (it means millions), still in 4.9, 4.8… and from version 5 and above, just check how may millions of times have been download the classic editor plugin to still working in an easy, clear and safe mode ;). Just and opinion…

Brad says:

April 27, 2020 at 9:34 am

Pete is entitled to his opinion, but I strongly disagree that ACF Blocks is a hack. It’s a much needed bridge for some WP developers who are struggling to get up to speed with React. Not to mention all the use cases where having settings in the sidebar is what you want anyways.

Nicolas Scott says:

April 28, 2020 at 7:25 pm

I agree with Brad. Just the other day I was doing a site build and needed some custom markup that the client could easily edit. I dusted off the ACF Block documentation that I hadn’t looked at for a while and had exactly what I needed in a few minutes. The nice thing is it saves the data right in post_content, too so doesn’t take up meta table space for simple formatting purposes. My mind is so invested in PHP and SCSS as a one-man developer shop. I use jQuery where I need to modify the DOM. And as much as I’d love to be up to speed on modern JS and React, I just don’t know where to start and when (especially now that the family is home ALL THE TIME (4 kids 7 years and under). AHAHHHHH!

Reply

dzulfriday says:

April 28, 2020 at 7:52 am

The Block Lab team was hired by WP Engine. They discontinued the development of new features, so it’s not a very promising option to develop WordPress blocks anymore.

Jonathan Bossenger says:

April 30, 2020 at 1:26 am

That’s what the attributes object is. It’s pretty much identical to React’s state management concept, a top level object that keeps track of properties and what’s changed. Thank you for this!!! From the docs I couldn’t understand what the block attributes were supposed to do, then I read this and it all clicked into place.

clifgriffin says:

July 15, 2020 at 1:37 am

I am the creator of a plugin that adds functionalities for adding code into wordpress in a per-page or per-post basis. https://wordpress.org/plugins/ultimate-shortcodes-creator/ It can be done via shortcodes or Gutenberg Blocks. It’s lightweight and no overload is paid if the shortcode is not present in the page. Code can include php, js, css, and even ajax code. Also, scripts code can be inserted via or footer. May be is interesting for someone.

Mark Lee says:

July 17, 2020 at 11:13 am

Nice dev tutorial that also raises issues of strategies and user concerns. Somehow it seems to me that at the base, WordPress is losing its focus as a BLOGGING platform. Blogging is about writing and maybe sharing some images. More advanced users are also interested in or concerned about design and tinkering. Block editing sends novice coders like me into the stone age. For example, after setting up a post on a full-width page with no sidebar (because the theme doesn’t make the sidebar responsive), I wanted a tiny script, rather than another plugin, to make a shortcode to add to a a right column. Thanks to the WP support group, I was able to do it after 12 hours when it didn’t display or appeared at the top of the page with JSON errors. And this wasn’t even React, just plain old PHP code. Fifteen minutes tops if I really knew what I was doing. To create a Gutenberg sidebar block, from the sound of this post that’s three months for me. Blocks are entirely about design and editors such as Gutenberg and the popular Elementor, are not post-friendly. For example, Elementor does not even sell the idea of creating POSTS. So their freebee app does not even make creating a post simple. That’s in their paid version. But this is about Gutenberg. It’s even less intuitive than the commercial products. With Web presentation being increasingly driven by mobile and tablet viewers, design options are narrowing as UI considerations focus on user interactions (ease of navigation, clicks, form filling while conserving real estate etc). The wide canvases of the desktop are mainly for content creators and office functions. It’s not nice using a block editor on my little tablet. Bottom line then, is that block editors are suited for a declining market of layout that mimics magazines and newspapers and now, rightly, take the form of the applications like PageMaker and QuarkXpress. There’s no use for a right aligned photo on a phone. Properly done, the block editor should obviate the need for themes as a few templates should suffice with WordPress shipping with a blank table for the designer to play on. What we have is something we can’t describe as a horse, a camel or a giraffe. When I start LibreOffice Write, I know exactly what I’m about to do and when I open Scribus, I don’t expect to be preparing an interoffice memo. And that’s the problem with Gutenberg. Clicking Add New from the Posts menu doesn’t begin an intuitive experience. P.S. A negative about the block editor environment is that you’re completely locked out of the admin interface.

Michael McGlynn says:

December 18, 2020 at 3:04 pm

Great article and well considered. Thank you for writing it.

Kristina Bressler says:

March 11, 2021 at 12:21 pm

The Gutenberg Examples repo that you mentioned. On their main page, the installation section mentioned:

Download a pre-built zip archive of the latest release. Do not download from the "Clone or download" GitHub button, as this includes the source material only. Read the Development instructions below if you’re interested in building your own copy of the plugin.

This is what I see before clicking on the link to download the files. However, what I see is this: <img width="1023" alt="Screen Shot 2021-03-11 at 9 48 23 AM" src="https://user-images.githubusercontent.com/5368455/110814362-fedeb400-824e-11eb-9519-4f2a0cccd6d2.png"> I download both the gutenburg-examples.zip and source code in order to look at both folders. The source code has package.json, etc that the gutenburg-examples.zip doesn’t have. I’m trying to follow the block tutorial from develop.wordpress.org: https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/writing-your-first-block-type/ So which one should I be using to edit as I follow the block tutorial?

James Hunt says:

March 18, 2024 at 1:52 am

If you want a @wordpress/create-block experience but with ACF blocks, I created this npm package to quickly scaffold ACF blocks in to your theme https://github.com/thetwopct/create-acf-block-json

Brad D says:

March 19, 2025 at 3:59 am

Thank you. I find npm start deletes the blocks-manifest.php file and i need to use npm run build to get it back so i can load the site. I wonder if it’s caused by not installing Python?

YoUseF Abdallah says:

April 20, 2025 at 10:54 pm

Mike, this is an incredibly comprehensive guide! Your comparison between React-based blocks and ACF Blocks really helps clarify the trade-offs between these two approaches. I recently published a tutorial on https://wpdive.com/blog/create-custom-gutenberg-blocks-wordpress that complements your technical deep-dive. While your article focuses on the developer perspective, I explored how non-developers can leverage tools like Lazy Blocks to create custom blocks without touching a single line of code. I especially appreciate how you’ve highlighted the steep learning curve for React development. This echoes my experience – many WordPress developers still prefer PHP, which is exactly why ACF Blocks is such a game-changer. It bridges that gap perfectly by letting us use familiar PHP templates while still giving clients the modern block editor experience. The Paranoia reference made me laugh! I’ve always thought that dashicon had an ominous look to it. Thanks for sharing such a detailed resource – looking forward to seeing more block development content from your team!