Integrate ACF blocks with Gutenberg styles

It’s been a while since I’ve had the opportunity to build ACF blocks (I took a break to learn how to build blocks with React), but I got to make some in a recent project I worked on. I was pleasantly surprised at how much easier it was to use ACF blocks, especially with the advent of ACF integrating with block.json. However, I still assumed that the integration with WordPress’ growing list of block supports was lacking. Turns out, not so much.

Previously, if I wanted my block to support padding, margin, colors, or anything else Gutenberg supported natively, I had to check and generate those styles myself. Maybe I just never knew about this. Yeah, it’s silly I didn’t know this sooner. But! While researching this article and trying to back-track how I figured out how to do this, my resolve was strengthened: WordPress’ documentation is so horribly disorganized and all over the place, it’s challenging to put pieces of an idea together.

Hopefully, having all their different articles linked in one place will be helpful to someone. Here’s the quick and easy way I found to have ACF support basically all styles Gutenberg generates for it. This includes padding, margin, colors, fonts, classes, and anchors.

Stick this in your ACF block’s PHP file (probably render.php):

<?php
    $block_atts    = get_block_wrapper_attributes();
?>
<?= !$is_preview ? '<div '. $block_atts . '>' : '' ?>

    <InnerBlocks />

<?= !$is_preview ? '</div>' : '' ?>

What would you know, it’s simple as that. And based on how WordPress handles dynamic blocks, too. (After I wrote this, I found that ACF had the same solution on their website)

As a bonus, you can add your own classes, styles, and other attributes to the block wrapper (similar to what you can do in React):

<?php
    $block_atts    = get_block_wrapper_attributes(array(
        'class'     => 'custom-class-name',
        'aria-label'=> __( 'Label' ),
        'style'     => 'background-color: red;'
    ));
?>
<?= !$is_preview ? '<div '. $block_atts . '>' : '' ?>

    <InnerBlocks />

<?= !$is_preview ? '</div>' : '' ?>

As ACF’s website explains, I’m including the $is_preview variable (one of a few PHP variables that are available in the ACF block render callback) to determine if I should render the outer tag in the Editor. This is because, inside the Editor, Gutenberg already provides the block’s wrapping element with its generated styles. If you render the block attributes twice, you’ll get twice the padding, margin, and styles.

As a bonus, here are some additional block supports I typically use in my block.json. These aren’t listed publicly, since they’re experimental, but they’re definitely helpful:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "package/block-name",
    "version": "0.1.0",
    "title": "Block Title",
    "category": "widgets",
    "icon": "smiley",
    "description": "Example block scaffolded with Create Block tool.",
    "example": {},
    "acf": {
        "mode": "preview",
        "renderTemplate": "render.php"
    },
    "supports": {
        "html": false,
        "className": true,
        "color": {
            "text": true,
            "background": true,
            "link": true
        },
        "layout": true,
        "alignWide": true,
        "typography": {
            "fontSize": true,
            "lineHeight": true,
            "__experimentalFontWeight": true,
            "__experimentalFontFamily": true,
            "__experimentalTextTransform": true
        },
        "spacing": {
            "margin": true,
            "padding": true,
            "blockSpacing": true
        },
        "__experimentalBorder": {
            "color": true,
            "radius": true,
            "style": true,
            "width": true
        }
    },
    "textdomain": "",
    "editorScript": "file:./index.js",
    "style": "file:./style-index.css"
}

Resources

WordPress: Block wrapper attributes
WordPress: List of block supports (non-experimental)
ACF: Block Wrapper attributes
ACF: Block Variables