Creating custom Gutenberg/Block Editor blocks with ACF is a great way to provide WordPress users with the functionality of custom blocks without having to be familiar with Javascript and React. If you haven’t tried this workflow before, the experience is largely similar to how ACF was used before the advent of the Block Editor. There is the extra step of having to register the block (using PHP, still no Javascript necessary!) to make sure WordPress knows you’re trying to build a new block. But after that’s done, you add custom fields to it through the same ACF interface you’re already familiar with, and build the template for controlling how the block displays with get_field and the_field calls just the same as you always have. The code to register a block looks something like this:
acf_register_block_type( array(
'name' => 'image-with-text',
'title' => __('Image with Text'),
'description' => __('A custom block for Image with Text.'),
'render_template' => 'template-parts/blocks/image-with-text.php',
'category' => 'ap-blocks',
'keywords' => array( 'text, image, image with' ),
));Code language: PHP (php)And with that, we’ve registered a new “Image with Text” block that will now be available inside the Block Editor. However, for adding that last extra bit of polish, let’s take a look at how we can add a custom icon to our new block.
Custom Icons in ACF Blocks
In our register block code, we can specify an icon parameter, which tells ACF that we want a custom icon. We can either specify a string for a Dashicon (an icon set included with WordPress):
acf_register_block_type( array(
'name' => 'image-with-text',
'title' => __('Image with Text'),
'description' => __('A custom block for Image with Text.'),
'render_template' => 'template-parts/blocks/image-with-text.php',
'icon' => 'book',
'category' => 'ap-blocks',
'keywords' => array( 'text, image, image with' ),
));Code language: PHP (php)You can even include a custom SVG if you have one you’d rather use:
acf_register_block_type( array(
'name' => 'image-with-text',
'title' => __('Image with Text'),
'description' => __('A custom block for Image with Text.'),
'render_template' => 'template-parts/blocks/image-with-text.php',
'icon' => '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>',
'category' => 'ap-blocks',
'keywords' => array( 'text, image, image with' ),
));Code language: PHP (php)However, this method means that you have to paste the hardcoded SVG string into every block you want to register with that icon. If you’re registering many blocks with the same icon, and decide that icon needs to change in the future, you have to replace that hard-coded SVG string on every block. Luckily, there’s a way to make using the same icon for multiple blocks much more efficient.
Use an SVG file instead of a hard-coded string
If there’s an SVG file in your theme that you want to use for your custom blocks, you can use file_get_contents to get the SVG code out of the file and into your register block call without hard-coding the SVG string. Here’s what that looks like:
acf_register_block_type( array(
'name' => 'image-with-text',
'title' => __('Image with Text'),
'description' => __('A custom block for Image with Text.'),
'render_template' => 'template-parts/blocks/image-with-text.php',
'icon' => file_get_contents( get_template_directory() . '/images/svgs/image-with-text.svg' ),
'category' => 'ap-blocks',
'keywords' => array( 'text, image, image with' ),
));Code language: PHP (php)You’ll need to update the file path to reflect where the image actually exists in your theme, but if you ever wanted to update the icon, you could do so just by updating that one SVG file and all the blocks that reference that file will now be updated as well.
Heads up!
Loading SVG code like this can potentially be a security concern (similar to why the WP Media Library doesn’t support SVGs by default) so make sure any SVGs you have included this method have been inspected to make sure they’re safe and contain only the code needed to render the image.
That’s it!
You know should be able to use your custom SVGs while keeping your register block calls nice and DRY.
Need more help?
If you’re taking on new Block Editor project or exploring how to transition your site to the new Block Editor, reach out to hello@alphaparticle.com and let’s see how we can help.