Meta Box Compatibility Flags

The new block editor has the ability to load meta boxes, to help plugins transition to the new Gutenberg platform. This compatibility functionality works fairly seamlessly with basic meta boxes, but more complex uses may require modification, particularly those that make heavy use of DOM-dependent JavaScript.

To help ensure end users have the best possible experience, there are two flags you can set when adding a meta box, which WordPress will use when determining when to load the block editor, or to fall back to the classic editor.

Flags

__block_editor_compatible_meta_box

This flag lets you set whether the meta box works in the block editor or not. Setting it to true signifies that the you’ve confirmed that the meta box works in the block editor, setting it to false signifies that it doesn’t. If the flag isn’t set, then WordPress 5.0 will assume that the meta box does work in the block editor.

__back_compat_meta_box

This flag lets you set whether the meta box is intended to be used in the block editor, or if it has been replaced by block-based functionality. Setting it to true signifies that this meta box should only be loaded in the classic editor interface, and the block editor should not display it. Setting it to false signifies that this meta box is intended to be loaded in the block editor. If the flag isn’t set, then WordPress 5.0 will assume that the meta box is intended to be loaded in the block editor.

Usage

These flags are used by passing them in the $args parameter of add_meta_box(), like so:

add_meta_box(
	'my-meta-box-id',
	__( 'My Meta Box', 'textdomain' ),
	'my_meta_box_callback',
	'post',
	'advanced',
	'default',
	array(
		'__block_editor_compatible_meta_box' => true,
		'__back_compat_meta_box'             => false,
	)
);

Fallback Warnings

WordPress 5.0 also contains a developer preview of a fallback warning. If you set WP_DEBUG to true, then create a meta box with __block_editor_compatible_meta_box set to false, and __back_compat_meta_box either undefined, or set to false as well, this warning will show in the classic editor.

Screen shot of a demo meta box showing the fallback warning.

This warning is currently intended to be a developer preview, hence why it’s hidden behind the WP_DEBUG flag, and requires a particular combination of the compatibility flags to be set. The wording and appearance of the warning will likely change in future WordPress versions, but it’s ultimately intended to help end users identify which plugin is responsible for a meta box.

If you register your meta box with the __back_compat_meta_box set to true, then this warning will never be displayed with your meta box, now, or in future WordPress releases.

Future Changes

Future versions of WordPress may change how they behave when these flags are set. For example, WordPress 5.0 will silently fall back to the classic interface when an incompatible meta box is encountered. Classic editor code will likely be moved to the Classic Editor plugin in the future, however, so those future WordPress versions would require the Classic Editor plugin to be installed before it could automatically fall back. Any such changes would be posted well in advance, to ensure there’s plenty of warning for testing changes.

#5-0, #dev-notes