Building Gutenberg Blocks with Advanced Custom Fields

Every person has their favorite set of tools. When we are not able to use those tools to complete a task, the feeling can be overwhelming. What do I do now? How will I accomplish what I need to do? I felt some of these feelings when I heard about Gutenberg, the new WordPress editor. If Gutenberg was block-based, what would happen to my custom page builder I created using Advanced Custom Fields?

Just Released, Pro Users Only

As of May 8th, 2019, this feature is now available for production-ready websites to ACF users with a Pro account. You can learn more about these feature release over at ACF's recent blog post, ACF 5.8.0 Release – PHP Blocks for Gutenberg

Presentation Material

I was pretty excited about this opportunity, so when I saw the first blog post about this future feature, I decided this was something I needed to share with the wider WordPress community. I submitted “Building Gutenberg Blocks with Advanced Custom Fields” to WordCamp Phoenix (and a few others since then, like WordCamp Miami).

It was incredibly well received at WordCamp Phoenix, with many people having the same feelings of fear around how they would continue to use ACF with the new editor. You can watch the presentation over on and review my slides on SpeakerDeck. I also gave this presentation at WordCamp Miami which you can watch the recording of here.

Let’s Dig In

Let’s dig into the part that you are likely here for, how to actually build the blocks!

To prefix this tutorial, the best place to learn how to do this is in the ACF documentation as they will continue to keep that material up-to-date. This blog post assumes you have ACF PRO 5.8.0 Beta4 or higher installed.

Decide Which Block You Want to Create

First, we need to decide what type of block we want to create. I created a Hero block where you could apply an image background and display content on top of it. I figured this is a pretty straight-forward way to get started and a block that, in my opinion, should be a core block.

Gutenberg Hero Block created with Advanced Custom Fields

Register Your Block

Let’s talk about the functionality that makes the block creation possible. We can use acf_register_block ( $settings );, an array of arguments for registering a block type.

I won’t bring all the settings into this because they will likely evolve and change, so always look for the latest information in the ACF documentation.

You can see in the following Github Gist, that I am registering my Hero block.

Example: (GitHub gist)

Create Your Field Group

Now that I have registered my block, I can create a field group in my WordPress admin and associate it with the new block I registered.

Gutenberg Hero Block created with Advanced Custom Fields. Field Group

Build Your Block Markup

Now that we have registered our block & created our ACF field group, it’s time to create the output for how our block will appear. For this example, I will be using the render_callback method — an alternative to this would be the render_template method, where you can put your output in a specific template file.

In the following Gist, lines 46 to 57 probably look pretty familiar to you. We are creating HTML and bringing in our field data where we need it. In lines 31 through 45, we are registering that callback and associating it with our block as well as bringing in my ACF field variables.

Embed: (GitHub gist)

Finished Block

Gutenberg Hero Block created with Advanced Custom Fields, Editing Block

I wrote a small amount of CSS to style the frontend of my block, but other than that, we are done, our block is ready to be used! All of the block code is available in a Github Gist.

Embed: (GitHub gist)

It’s Your Turn

I hope this post has given you an introductory comfort-level to building Gutenberg blocks with Advanced Custom Fields. I would love to see what you build — share your code snippets in the comments below.

Topics Content, Development, Guides and Tutorials, Website Technology, WordPress