Block Wrapper Props: useBlockProps

When building a block with Block API 2+ a React hook is available for better control over the wrapping element in the editor that serves as the outermost parent element for the block. In older versions of Gutenberg we did not have easy control over the wrapping element for the block so changing the markup of it, or adding class names, style props, data attributes, etc was clunky.

Old method in WP < 5.6

In the past with Block API 1 and WP < 5.6 we had to use the `getEditWrapperProps()` function which was an undocumented method on the `registerBlockType()` function that could give us some ability to add data to the wrapping element. The approach was less than ideal however and not very discoverable or easy to understand when looking at the block’s markup and the JSX in the edit function.

// Add column class to edition block editor wrapping element.
getEditWrapperProps( attributes ) {
     const { columnClass } = attributes;

     if ( columnClass ) {
          return { 'data-column': columnClass };
     }
},

Examples:

New Method in WP 5.6+:

With WP 5.6 Block API 2 was introduced and brings a much better and easier way of controlling the wrapping element around your block in both the Editor AND in the Save function or dynamic block PHP template. Block API 2 gives us the new useBlockProps React hook, but there are some other advantages. Markup the editor is much cleaner for Block API 2 blocks, with less wrapping elements which helps ensure blocks in the editor render better with the same frontend styles. Additionally useBlockProps has a version for the InnerBlocks component as well. In the past the InnerBlocks component produced truly awful markup in the editor and broke our styles for child elements. For instance you’d see 2 or 3 extra wrapping divs and so the frontend styles for a flex layout or floated child elements would break and editor specific styles would need to be added to try to address it. Block API 2 and using useBlockProps helps to reduce all of that extra markup junk and give us a block in the editor that is much closer to the frontend markup of the block. Less styles and hacks for us to have to patch in the editor to get the block looking good.

This hook simplifies several tasks, including:

Assigning a unique id to the block’s HTML structure.
Adding various accessibility and data- attributes for enhanced functionality and information.
Incorporating classes and inline styles that reflect the block’s custom settings. By default, this includes:
- The wp-block class for general block styling.
- A block-specific class that combines the block’s namespace and name, ensuring unique and targeted styling capabilities.

This hook is used to lightly mark an element as a block element. The element should be the outermost element of a block. Call this hook and pass the returned props to the element to mark as a block. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

Edit function:

To use the new Block API 2 or higher you must opt-in to it in your block’s block.json file or in registerBlockType by specifying apiVersion: 2
Import useBlockProps from @wordpress/block-editor package.
In the edit function you’ll usually want to keep things nicely organized by declaring a const for blockProps and then passing an object in with the parameters you want to set on the wrapping element
In your return statement which usually has JSX, you can specify your wrapping HTML element and simply spread the blockProps object {...blockProps} which will result in those parameters being output such as class="my-class" style="background: #cc000" data-myname="something"

Save function:

For the Save function when using this with a static block you’ll need to use useBlockProps.save()and pass the same properties object and then spread the props on the outer element in your return function

render.php (dynamic blocks):

For a dynamic block, you can use the `get_block_wrapper_attributes()` function on the wrapping element of your block template. See documentation.

Note: The get_block_wrapper_attributes() function will only output the classnames generated for the block. You will need to manually output additional attributes such as data attributes, style attributes, etc. The function does support a parameter that lets you pass some specific attributes but which are supported varies based on the version of WordPress so check the documentation.

<p <?php echo get_block_wrapper_attributes(); ?>>
    <?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', 'block-development-examples' ); ?>
</p>

Note:

The useBlockProps adds classes and important properties to your block in the editor and the frontend even if you aren’t passing any extra custom values to it. Features such as color support, alignment, etc are automatically added to the block via the useBlockProps hook so be sure to include it in your block’s edit function and in the save function so that those classes, id’s and other data attributes are properly output and your block functions as it should.

Block Wrapper Props: useBlockProps

Old method in WP < 5.6

Examples:

New Method in WP 5.6+:

Edit function:

Save function:

render.php (dynamic blocks):

Note:

Output:

Examples:

Related Documentation