Enqueueing Scripts and Styles for Gutenberg Blocks

Before we start building new blocks for the Gutenberg editor we need to know how to properly enqueue scripts and styles. Thankfully WordPress makes this easy with two new hooks.

Reading Time: 4 minutes

To get started building blocks for Gutenberg we’re going to need a way to let WordPress know our blocks exist.

Since Gutenberg blocks are built with JavaScript we’ll need to enqueue our scripts and any styles associated with the block.

This is done by using two new hooks introduced to WordPress specifically for enqueueing block assets. As well as the wp_enqueue_script and wp_enqueue_style functions.

The new hooks

enqueue_block_editor_assets – This can be used to enqueue block scripts and styles in the admin editor only.

enqueue_block_assets – This is used to enqueue block scripts and styles in both the admin editor and frontend of the site.

What to enqueue in the admin only

Since the main JavaScript for creating blocks is only needed in the admin editor you’ll want to use enqueue_block_editor_assets to include it.

You may also have styles that are only relevant to the editor. In that case you’ll want to enqueue those using enqueue_block_editor_assets as well. This could be something like focus states for an input or other indicators to show the user what is editable in the editor that isn’t needed on the frontend.

What to enqueue in the frontend only

In some cases you may need JavaScript that runs in both the frontend or the backend. For example, if you’re building a slider block you would want the sliding functionality to work in both instances. In that case you can load those scripts with enqueue_block_assets.

Since the idea behind Gutenberg is to tie the frontend and editor content together visually you’ll most likely have the bulk of your CSS displayed on both the frontend and editor. This again would use enqueue_block_assets.

In the case you have some style that needs to only be included within the frontend and not the editor you could use the enqueue_block_assets hook and run an ! is_admin() check to enqueue your script or style.

A word on dependencies

When you’re building blocks for the new Gutenberg editor there are a few JavaScript libraries that you’ll want to include within the dependencies parameter of your wp_enqueue_script function.

These are wp-element, wp-blocks, wp-components, and wp-i18n. These will give you access to several powerful tools to make your life developing blocks easier.

At a minimum, you will need to enqueue scripts for your block as part of a enqueue_block_editor_assets action callback, with a dependency on the wp-blocks and wp-element script handles.

Let’s take a look at what these cover.

wp-element – This handle gives access to wp.element which is an abstraction layer atop of Reach that can be used for creating elements. Having an abstraction layer allows WordPress to safeguard against any future changes to React by have a centralized version of the code. Check out the Github readme on Element for more information.

wp-blocks – This handle refers to wp.blocks which gives access to components and functions used for building blocks. Things like registerBlockType are found here. Again you can find more details on the Github readme on Blocks.

wp-components – While not required like wp-element and wp-blocks, the wp-components library is helpful in block development as it contains React components that can be used to create a consistent editor experience. Things like tooltips, popovers, and spinners can be found here. Explore the Github directory for Components to see what else is available.

wp-i18n – Again this isn’t required, but it is a good practice to include as this gives you easy access to the internationalization functions that can be used within JavaScript. If you’re familiar with the __() used within WordPress you’ll be able to use this in a similar fashion within JavaScript.

Let’s pretend we’re using this in a plugin hence the plugins_url() path.

Putting it together

Now that we know what we’re working with we can confidently start enqueueing scripts and styles for Gutenberg blocks. Let’s put it all together.

Even though we’re showing an example of enqueueing block scripts and styles in a plugin here. You could also enqueue styles from within a theme to make sure blocks fit your design.

In fact there’s an interesting ticket on Github now discussing how base and theme block assets will be bundled and loaded with Gutenberg.

But wait there’s more!

So now that we’ve gone through enqueueing assets with enqueue_block_editor_assets and enqeueue_block_assets I should point out there is another way.

If you look at the handbook1, you’ll see it shows enqueueing scripts and styles a different way.

Instead of using the enqueue hooks we’ve gone over, the script and styles are registered with wp_register_script and wp_register_style. Then passed to the register_block_type function registration settings.

There are 4 options to use in this method:

editor_script and editor_style which are only enqueued in the editor. And script and style which are enqueued on both the editor and when viewing the frontend.

All done within the init hook. Here’s an example from the handbook.

I prefer the enqueue_block_editor_assets and enqueue_block_assets methods. It’s more inline with the current method for adding editor styles using add_editor_style. And you have flexibility for enqueueing multiple files. If that use case arises.

Resources on Enqueueing Scripts and Styles for Gutenberg Blocks

Big thanks to Zac Gordon for his The Gutenberg Development Course for getting my research into this topic started. I highly recommend you take it.

  1. At least at the time of writing.