Block API

The WordPress Block API is a fundamental part of the WordPress editor that allows developers to create and customize content blocks within the Gutenberg editor, providing a structured framework for building reusable content elements like paragraphs, images, headings, and more, which can be easily integrated into a website through plugins and themes; essentially acting as the foundation for extending the editor’s capabilities with custom blocks.

Version 3 (>= WordPress 6.3)

  • The post editor will be iframed if all registered blocks have a Block API version 3 or higher. Adding version 3 support means that the block should work inside an iframe, though the block may still be rendered outside the iframe if not all blocks support version 3.

Comes in WP 6.3 and provides access to the iframe version of the block editor. Prior to 6.3 the Block Editor is rendered on the page in the admin as part of that page. This has presented challenges, styles especially have to be retargeted with the add_editor_style() feature to target the appropriate div on the page so styles to leak and effect the WordPress UI. We don’t have access to this yet and haven’t tested it yet.

It is important to note that for the iframe editor to be enabled All Blocks that are registered must be using Block API 3. Additionally there can’t be any classic metaboxes on the page. That means we will have some work to do to both update all of our blocks AND remove or replace all traditional metaboxes we have. Those are scattered across multiple plugins (BU Blocks, BU Post Details, etc).

Related Documentation

Version 2 (>= WordPress 5.6)

  • To render the block element wrapper for the block’s edit implementation, the block author must use the useBlockProps() hook.
  • The generated class names and styles are no longer added automatically to the saved markup for static blocks when save is processed. To include them, the block author must explicitly use useBlockProps.save() and add to their block wrapper.

Released with WP 5.6. It is declared in the block.json file or during the block registration like so:

// Register the block.
const asideBlock = registerBlockType( 'editorial/aside', {
	apiVersion: 2,
	title: __( 'Aside' ),
	description: __( 'Add an aside with related information. Accepts image, headline, paragraph, and button blocks as children.' ),
	icon: blockIcons('aside'),
	category: 'bu-editorial',
	supports: {
		align: [ 'left', 'right' ],
	},
	attributes: {
		themeColor: {
			type: 'string',
		},
	},

	edit,

block.json example:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "bu/block-starter-dynamic",
  "version": "0.1.0",
  "title": "BU Block Starter",
}

Block API 2 gives us a new superpower: the ability to specify and determine what the block’s wrapping element is. This gives us much greater control over the markup of the block in the editor and helps make the frontend styles for the block apply in the editor better. It reduces how much “extra” markup WP adds to the block in the editor. It does the same for Inner Content elements when there are nested blocks inside a block. Prior to this designers had a real struggle with nested blocks because WP injects extra wrapping DOM elements and so styles that might build a grid or flexbox layout have to be retargeted to a new element in the editor.

Block authors must use the new useBlockProps() hook. This let’s you specify in your edit function which element is the block’s container and useBlockProps() will output all of the classnames and other attributes needed on that containing element. Example.

const blockProps = useBlockProps( {
	className: classnames(
		className,
		{ 'is-open': isOpen },
		`icon-style-${ iconStyle }`
	),
	style: styles,
} );

return (

	<div {...blockProps}>

You can see in this example how useBlockProps() can be passed more than just the classnames for the block. It is used for outputting all other HTML attributes on that element such as style and data attributes.

Related Documentation

Version 1

Initial version. (apparently that’s all anyone needs to know)

Recommendations

  • We should keep our blocks updated on the newest Block API Version appropriate for our installed version of WordPress
  • We should be mindful of WordPress upgrades and plan to update existing blocks to a newer Block API Version or at the least perform testing to determine the change and impact.
    • Special note about Block API 3: We should have a plan on the roadmap to update blocks to Block API Version 3 to make use of the iframe editor however this will also require us to replace and remove all existing classic metaboxes registered in the admin. Those will need to be replaced with a block editor equivalent. (Block Editor Plugins? for the sidebar) In order for the iframe version of the Block Editor to be used all registered blocks must be apiVersion: 3 and there can’t be any classic metaboxes in use on that editor.
  • When building blocks, the designer should be consulted on the markup for the block container, class names, etc.

Related Documentation