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.
<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:
<div class="my-class wp-block-your-block-name alignright">
</div>
Considerations
Links in the Editor
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.
<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.
<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.
<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:
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.