How to Use to registerBlockType() to Create Blocks in WordPress

I have wanted to write a blog post on the registerBlockType() JavaScript function in WordPress for a while now.  While working on my Gutenberg Development Course I learned that this function is at the heart of Block Development in WordPress since you must use it to create custom blocks.

How to Access registerBlockType()

The creation of a block in WordPress (as of writing) is done via JavaScript (not PHP) using a function called registerBlockType().

This function lives inside of the wp.blocks library, which contains helpful functions for block creation, as well as the core WordPress blocks themselves.

WordPress makes this function accessible as a global variable in the window object as wp.blocks.registerBlockType().

Here is a shortcut you can add at the top of your JS file to “import” this function into your code:

NOTE: At the time of writing, wp.blocks is NOT available as a package you can actually import into your code as you would other packages.  It is only available via the global window object.

registerBlockType Name and Settings Parameters

The registerBlockType() function takes two parameters: name and settings.

  • name [string] –  “Block names must contain a namespace prefix, include only lowercase alphanumeric characters or dashes, and start with a letter. Example: my-plugin/my-custom-block” Source
  • settings [Object] – The settings parameter is an object with several predefined properties that must be assigned for your block to work.  We will look at these in more depth.

Here is what this would look like without all of the settings configured.

registerBlockType Settings

The registerBlockType() settings object has seven properties that include both meta information about the block as well as methods controlling the UI and functionality for the block in the editor and on the frontend.

  • title [string] – The title setting gives your block a searchable, human readable name. It should be escaped using wp.i18n.__().
  • category [string] – The category setting determines under which heading a user can find your block. Options include “common”, “formatting”, “layout”, “widgets” and “embed.”
  • icon [Dashicon|Element] – The icon setting for registerBlockType determines what icon will represent your custom block. Can use a WP Dashicon or custom SVG.
  • keywords [Array] – The keyword setting provides three additional keyword / phrases that will display your block when searched for. Limited to 3.
  • attributes [Object] – The attribute setting identifies what dynamic content we are using in our blocks. Several attribute options exist depending on what types of data we are using. Attribute settings are optional if your block uses no dynamic data. This data is then made available via Read more.
  • edit [function] – The edit setting determines what be displayed in the editor area for the block. Must return a valid React element using wp.element.createElement() or JSX. Also accepts dynamic data as a props parameter.
  • save [function] – The save setting determines what be displayed when the block is converted to content for the frontend. Must return a valid React element using wp.element.createElement() or JSX. Also accepts dynamic data as a props parameter.

The first four of these [title, category, icon and keywords] are more for the user and include meta information about the block itself.  The last few settings [attributes, edit, save] are a bit more complex and control the actual functionality of a block.

Example of registerBlockType in Action

In order to show all of the settings in action, particularly the attributes setting, we need to have a block with some sort of dynamic data.

Below is an example of a simple block with one editable field.  This shows registerBlockType() in action with all it’s parameters and settings.

Depending on your comfort level with JavaScript (and possibly React) the code above may make sense, or there may be a bit inside of attributes, edit and save that doesn’t make complete sense.

Hopefully though, this post helps you understand the basics of how registerBlockType() works and gives you a basis to get started with it.

Learn More About Building Blocks in WordPress

To learn more about building blocks and other aspects of Gutenberg Development, please check out my Gutenberg Development Course.

How to Add JavaScript and CSS to Gutenberg Blocks the Right Way in Plugins and Themes

How to Add JavaScript and CSS to Gutenberg Blocks the Right Way in Plugins and Themes

icon-256x256While working on my Gutenberg Editor Development Course I had a simple question early on: “How do I enqueue my block JavaScript and CSS to work with the Gutenberg Editor?

The short answer is there are two ways:

  • enqueue_block_editor_assets – For enqueueing JavaScript and CSS in the admin editor only.
  • enqueue_block_assets – Enqueues on both the frontend of the site and in the admin editor (unless !is_admin() is used then it just enqueues on the frontend only).

Enqueueing Block JavaScript the Right Way

In general, you will want to load your main block JavaScript using enqueue_block_editor_assets since your main block JavaScript code needs to execute inside the editor.

Once a block is saved as content, the editor JavaScript is no longer needed, so most JavaScript for building blocks only needs to execute in the editor.

On occasion your block may require JavaScript to run properly on the frontend.  For example, if you were building a slideshow or a form or some other element that needed frontend interaction.  In this case, you would break out that functionality from your main block JavaScript and load it separately using enqueue_block_assets.

Enqueuing Block CSS the Right Way

The general principal for styling blocks in the new WordPress editor is to make them look the same in the editor as they do on the frontend.  To accomplish this, we enqueue our main block styles using enqueue_block_assets.

There are some instances where you need to style blocks in the editor different from the frontend.  Some reasons for this are to help give users visual cues for what they can edit or there may be controls in the editor that need styling and do no appear on the frontend.  If there are ever styles you want applied only in the editor, you can break these into a separate CSS file and load it using enqueue_block_editor_assets.

On the chance that you have styles that should only be applied to the frontend and never loaded in the editor, you can load them using enqueue_block_assets and wrap your wp_enqueue_style call inside of a !is_admin() conditional statement.

Example of Enqueueing Block JavaScript and CSS in a Plugin

This example below would go in a main plugin file that needs to load blocks.  See how both enqueue_block_assets and enqueue_block_editor_assets are used.

Some notes on the example above:

  • We have a file /assets/js/blocks.js with our main block JS code.  This is being loaded with enqueue_block_editor_assets into the editor.
  • We have a file /assets/css/blocks.editor.css with our editor only styles.  This is also being loaded in the same function call as our JavaScript, which hooks into enqueue_block_editor_assets.
  • Then we have a file /assets/js/blocks.shared.js with additional JS code that needs to be loaded on the frontend and backend.  This is being loaded with enqueue_block_assets into the editor and frontend.  Note, you may or may not need JavaScript loaded on the frontend depending on the type of blocks you build.
  • We also have /assets/css/blocks.styles.css, which is our main CSS file.  This will load on the front and backend since we have it hooked into enqueue_block_assets.
  • The final file /assets/css/blocks.frontend.css is wrapped inside of the !is_admin() conditional statement so it will not load in the editor as is usually the case with enqueue_block_assets. Note, you probably don’t need a frontend only stylesheet.  It is also recommended to use editor only styles to override shared frontend/editor styles rather than this approach demonstrated here for example purposes.

This should cover the basic use cases you will have for loading block JavaScript and CSS into your plugins.  Let me know if I missed something you find useful!

Example of Enqueueing Block CSS in a Theme

In general, you should NOT build blocks inside of themes.  Custom blocks should generally be built inside of plugins.  However, it is perfectly acceptable for themes to customize block styles, both in the editor and on the frontend.

The example below shows how to load CSS in your themes to override default block styles.  This code would go inside of  or be included into a theme’s functions.php file.

Some notes on the code above:

  • We are not including any block JavaScript since that should generally go in a plugin.
  • We have a file /assets/css/blocks.editor.css with our editor only styles.  This is being loaded using enqueue_block_editor_assets.  Note, there is a chance you may not need editor only CSS.
  • We also have /assets/css/blocks.styles.css, which is our main CSS file.  This will load on the front and backend since we have it hooked into enqueue_block_assets.
  • The final file /assets/css/blocks.frontend.css is wrapped inside of the !is_admin() conditional statement so it will not load in the editor as is usually the case with enqueue_block_assets. Note, you will likely not need a frontend only stylesheet.  It is also recommended to use editor only styles to override shared frontend/editor styles rather than this approach demonstrated here for example purposes.

A Note on File Organization and Compilation

The examples above show including only a few final JavaScript and CSS files all within ‘/assets/js’ and ‘/assets/css’.  It is likely that you will break your JavaScript and CSS into smaller files and compile them using a tool like webpack.

If you bundle your final JS and CSS into a different directory structure than the ‘/assets/js’ and ‘/assets/css’ structure used above, you may need to make some changes to the examples.  Same goes for how you name your files.

The examples above do not offer insight into how you should organize your modular JS and CSS or how you would setup a tool like webpack to handle compiling it all.  I do have some thoughts on these matters and you can see my course below or wait for upcoming blog posts on these topics.  However, in general, try to follow modern best practices.

To Learn More About Developing with the New WordPress Editor

If you would like to learn more about developing blocks with WordPress, please check out my course Gutenberg Development.

Sneak Peak Video from My Gutenberg Development Course – “Important JavaScript Libraries that Ship with Gutenberg”

Since WordCamp US 2017 earlier this month, I have been working on a Gutenberg Development Course to help theme and plugin developers get up and running with the new editor coming to WordPress.

I still have some more recording to do at the time of writing, but I wanted to share one of the videos from the first section of the course where we talk about how Gutenberg works under the hood.

Important JavaScript Libraries that Ship with Gutenberg

In this video I go over four important libraries that are made available to us with Gutenberg:

  • wp.blocks
  • wp.element
  • wp.components
  • wp.i18n

At the time of recording, these are all made available in the global window object so we can access them in our own block code without having to import them.

To Learn More About Gutenberg Development

If you would like to learn more about developing with the new editor in WordPress, please check out my Gutenberg Development Course.

Create Additional Search Keywords for Your Gutenberg Editor Blocks

While working on my Gutenberg Editor Development Course I stumbled upon a cool feature for Gutenberg Blocks that let’s someone to find your block using words not found in the title of your block.

Searching for Blocks in Gutenberg

One of the easiest ways to find a specific block in Gutenberg is by using the search field.  By default, if your title has a keyword someone searches for, it will show your block in the results.

Sometimes though, we want our block to show for keywords that are not included in our title.


Here is an example of searching for “Image” and receiving multiple matching blocks

You can see in the example above that if we search for an “Image” block we get blocks that do not have “Image” in the title.

This is accomplished using the “keywords” parameter when registering your block.

Using the Keyword Setting When Creating a Block in Gutenberg

When you create a block using registerBlockType() you can set a parameter called “keyword.”  This parameter takes an array of words that if searched for, will include your block in the results.


Custom keyword allows block to be searched for using keywords not found in the block title

In the example above we have added extra keywords to a custom block.

Here is the code to make this work.  (Notice we are also escaping them using the wp.i18n library for localization).

This allows us to have our block show up for the search terms “zac,” “fire,” and “fuego,” which are not found in our block title.

I would suggest looking at what keywords the default WordPress blocks use and leverage some of those keywords in your blocks.

Learn More About Gutenberg Development

If you would like to learn more about creating custom blocks or developing with Gutenberg in general, please check out my Gutenberg Development Course!

How to Add Custom Icons to Gutenberg Editor Blocks in WordPress Using Dashicons or SVG

While working on my upcoming Gutenberg Editor Development Course I came across the question, “How do you create a custom icon for a block in the new Gutenberg editor.”  This post explains my process in figuring this out 🙂

Block Icons in the Gutenberg Editor

With the new Gutenberg editor in WordPress you have the option to select an icon to go along with your custom block.

Screen Shot 2017-12-07 at 4.51.01 PM

Example of icons with default block.

Using Default WordPress Dashicons as Block Icons

When you use registerBlockType() to create a new block, one of the parameters is “icon”.  You can use any default WordPress Dashicons as an icon.

In the example below we are using one of the default dashicons named “admin-settings“.  That will give us a settings icon like this.


Example of custom block with ‘admin-settings’ dashicon

Here is the code to make that work (focus just on the icon parameter):

Interestingly, if you look in the Gutenberg Core file ‘components/dashicon/index.js‘ you will see that dashicons are not being used the same way in blocks as they are in as in places like admin menus.  Instead, there is a case statement against each default argument, assigning it the proper SVG path.


Example of Dashicon component in Gutenberg Core assigning default SVG paths.

Creating Custom Gutenberg Block Icons Using SVG Paths

A lot of folks are going to want to create custom icons like this one.


Example of Custom Block with Custom SVG Icon

In the example above, I used an SVG icon from this collection here.  You can also create you own custom icons.

What you want to do is get the SVG path for your custom icon and create a custom SVG icon using that path.

Here is the code example from the image above.  Pay attention to the top, where iconEl is created then passed as the value to the registerBlockType() icon parameter.

You can use this model in your own code and simply replace the path ‘d’ value with the path for your own custom icon svg.

To Learn More About Gutenberg Development

To learn more about creating custom blocks and more with the new Gutenberg editor for WordPress, check out my Gutenberg Development Course.

“It works!” DesktopServer not working solution for Apache on Mac

I am not sure what I did to cause this problem, but recently, all of my DesktopServer server sites, including localhost began displaying the message: “It works!”

I contacted the lovely folks at DesktopServer and got this quick fix (for Macs):

This solved the problem and I’m back up and running.  Since I couldn’t find the solution online before I contacted support, I thought I would share 🙂

WordCamp New York 2017 JavaScript Workshop

WCNYC 2017.png

It’s been a good number of years since I last attended a WordCamp New York.  But it holds a warm place in my heart.  My first WordCamp was WordCamp New York 2008 🙂

This year, my good friend, David Parsons, took up the lead organizer role and put on a great WordCamp New York.

From the venue to the speakers, it all went very smooth and had a nice local camp feel.

Reflections From the JavaScript Workshop


My workshop was an adaptation of a similar workshop I have been doing at a number of other camps this year.

However, I learned one important thing this time.

It is important to take the time at the beginning to address who needs to “Learn JavaScript Deeply” from a programmer’s perspective and who just needs to know what it is capable of doing.

I noticed that some people loved learning vanilla JavaScript fundamentals and how to integrate with the WordPress REST API.  However, some people hung around through several hours of the workshop with not really realizing they did not need to learn JavaScript deeply as a developer. Some of these people were just savy website owners.

This supports something I have been saying for a while:

Compared to HTML and CSS, which you can learn a little and do a lot, with JavaScript you have to learn a lot to do a little.

All that said, for folks who wanted to learn JavaScript more deeply (or even just for the first time) I think the workshop went great.

Changes I’m Making for Next Time

There are a few modifications I am going to make for next time though:

  • Add a note at the beginning about “Who Should Be Learning JavaScript Deeply” and who can just learn to “Speak JavaScript”
  • With the decoupled Vanilla JS and WP REST API practice project we will just use fetch instead of introducing Axios or jQuery.
  • Inside of WordPress, when we import our decoupled example into a WordPress theme I am just going to show how to use jQuery AJAX.
  • Rather than try to teach the Backbone client I am just going to mention it at the end.  After teaching it for a while, I think it is best to know some Backbone before trying to use this.

You can view the slides and example files from the workshop here.

Learn More JavaScript!

WCNYC 2017 (1).png

Want to learn more JavaScript?

Head over the JavaScript for WordPress to learn about my Master Course to help you learn JavaScript more deeply.