Block API version 2

WordPress 5.6 will come with a new BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. version, enabling blocks to render their own block wrapper element. This is part of a larger effort to lighten the editor content’s DOM tree so that it matches the saved content (and therefore the front-end of the site). The biggest benefit of this is that themes and plugins can more easily style the block content if the markup is the same in the editor.

Enabling API version 2

To use the new API, you must opt-in to to API version 2. If you opt-in to API version 2, you must also render your own block wrapper element with the new API. To opt-in, set the apiVersion property to 2 on the block configuration object.

registerBlockType( name, { apiVersion: 2 } );

useBlockProps

When using API version 2, you must use the new useBlockProps hook in the block’s edit function to mark the block’s wrapper element. The hook will insert attributes and event handlers needed to enable block behaviour. Any attributes you wish to pass to the block element must be passed through useBlockProps and the returned value be spread onto the element.

import { useBlockProps } from '@wordpress/block-editor';

function Edit( { attributes } ) {
    const blockProps = useBlockProps( {
        className: someClassName,
        style: { color: 'blue' },
    } );
    return <p { ...blockProps }>{ attributes.content }</p>;
}

If you wish to use the element ref, you can pass one to useBlockProps.

import { useBlockProps } from '@wordpress/block-editor';

function Edit( { attributes } ) {
    const ref = useRef();
    const blockProps = useBlockProps( { ref } );
    return <p { ...blockProps }>{ attributes.content }</p>;
}

The save function must also use the save equivalent of the hook, useBlockProps.save.

import { useBlockProps } from '@wordpress/block-editor';

function Save( { attributes } ) {
    const blockProps = useBlockProps.save( {
        className: someClassName,
        style: { color: 'blue' },
    } );
    return <p { ...blockProps }>{ attributes.content }</p>;
}

Supporting both versions

If you use API version 2, it is recommended to set the Requires at least  header field to 5.6 so your pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party only updates after WordPress updates to 5.6. If users use an older version of WordPress, they would sensibly also use an older version of your plugin, hopefully encouraging them to update WordPress. It’s possible to do security fixes by releasing patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. versions for the older plugin versions, in case that is a concern.

If you really wish to support both API versions, you will need to register a different edit and save function for the previous version, either by loading a different block registration file entirely, or by passing the WordPress version number to JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. on the front-end and conditionally setting the edit and save function at the time of block registration.

API version 1

The block wrapper element is added by the framework with the contents of Edit inside of it.

function Edit( { attributes } ) {
    return (
        <p className={ someClassName } style={ { color: 'blue' } }>
            { attributes.content }
        </p>
    );
}

API version 2

The block wrapper element must be marked by the Edit component with the useBlockProps hook.

import { useBlockProps } from '@wordpress/block-editor';

function Edit( { attributes } ) {
    const blockProps = useBlockProps( {
        className: someClassName,
        style: { color: 'blue' },
    } );
    return <p { ...blockProps }>{ attributes.content }</p>;
}

#5-6, #block-editor, #dev-notes