Skip to content

useBlockProps

By default, Gutenberg has to create a wrapper around blocks to make them interactive inside the editor. This can become problematic for some block types like containers or columns, since the markup between editor and frontend will be different. The useBlockProps hook makes it possible to mark an element inside the block template as the root element, thus creating markup parity between editor and frontend.

Usage

Simply add the useBlockProps attribute to the root element of your block.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio will automatically combine classes and attributes from the editor (alignment classes etc.) along with whatever is defined in the block templates. get_block_wrapper_attributes is being used under the hood for that.

The blockstudio/blocks/components/use_block_props/render filter is applied to the wrapper in both the frontend and editor render paths. Classes added by a theme or a per-instance integration therefore appear in the editor canvas as well as the saved frontend markup.

Output:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

Considerations

Blockstudio prevents link navigation inside the block editor, including target="_blank", modifier-clicks, middle-clicks, and keyboard activation. Click events still reach Gutenberg, so ordinary clicks select the block. RichText remains editable. This applies with or without useBlockProps, including an anchor used as the block’s root element.

Frontend links and the browser’s context-menu commands are unchanged. You do not need to remove links from templates or branch on $isEditor.

Root Element

Since there can only be one root element in a block template, when using useBlockProps, the block template has to have a single root element. For example, the following will not work and Gutenberg will create a wrapper around the template.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

Similarly, useBlockProps can only be used once per block template.

@ Sign

Blockstudio converts the block template to valid React code inside Gutenberg using html-react-parser. This comes with the limitation that the @ character can’t be used inside an HTML attribute name.

Libraries like Alpine.js use the @ characters to define directives on HTML elements.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Inside Gutenberg, this @click attribute will be stripped from the element. (it will still work on the frontend, of course)

To combat this issue, you can use the alternative syntax Alpine.js provides.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

The above will work inside Gutenberg and on the frontend.

Canvas Body Classes

When assets.reset.enabled is active, Blockstudio also copies the sanitized classes returned by WordPress’s body_class filter to the block editor canvas. This keeps theme selectors such as .brand-a .site-card working in both places.

Filter the final class list when the editor needs a narrower set:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

This filter only controls classes copied into the editor canvas. It does not change frontend body classes.