Have you ever wanted to disable specific blocks in WordPress? Whether to simplify the editing experience, maintain consistency across a site, or any other reason, this article will guide you through the process.
At its core, block restriction in WordPress can be accomplished with either PHP or JavaScript. The choice between these two depends largely on your existing site setup and personal preferences.
For instance, extending your JavaScript code to include block restrictions might be the most seamless route if you’re already enqueuing a JavaScript file for tasks like creating custom block variations or other Editor enhancements. On the other hand, PHP offers a server-side solution that is easy to add to existing plugins and themes already part of your environment.
Either option will give you control over the available blocks in the Editor. Let’s get started.
Table of Contents
Configure personal preferences
While the primary focus of this article is disabling blocks with code, there is a no-code option as well. You can hide specific block types using the Editor’s preferences panel.
To do this in the Editor or Site Editor, click on the options menu, represented by three vertical dots at the screen’s top-right corner. From this menu, select Preferences. In the popup that appears, navigate to the Blocks section in the sidebar. Here, you’ll see a list of registered blocks. Check the ones you wish to hide.
These user-specific settings offer a convenient way to tailor the block inserter to your personal preferences, especially if there are blocks you never use. However, doing so will not restrict blocks for other users on your site. We will need some code for that.
Disable blocks with PHP
The first method uses PHP, specifically the allowed_block_types_all hook. The callback function for this hook accepts two parameters:
$allowed_block_types – An array of block type slugs or boolean to enable or disable all blocks.
$block_editor_context – The current block editor context.
It’s important to note that when using this hook to disable blocks, any block patterns composed of disabled blocks will also become unavailable for the user.
Using an allow list
Here’s a simple example that will only allow users to insert Heading, List, Image, and Paragraph blocks. This can be considered an “allow list.” All other blocks are disabled.
To test the following code, add it to a theme’s functions.php file or include it in a plugin.
/**
* Filters the list of allowed block types in the block editor.
*
* This function restricts the available block types to Heading, List, Image, and Paragraph only.
*
* @param array|bool $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
* @param object $block_editor_context The current block editor context.
*
* @return array The array of allowed block types.
*/
function example_allowed_block_types( $allowed_block_types, $block_editor_context ) {
$allowed_block_types = array(
'core/heading',
'core/image',
'core/list',
'core/list-item',
'core/paragraph',
);
return $allowed_block_types;
}
add_filter( 'allowed_block_types_all', 'example_allowed_block_types', 10, 2 );
Here’s what the block Inserter will look like when this allow list is applied.
Let’s make this example a bit more realistic with some conditionals.
You may only want to restrict Authors to these block types but give Editors and Administrators access to everything. You can use the current_user_can() function to do so. Update the code with the following.
/**
* Filters the list of allowed block types in the block editor.
*
* This function restricts the available block types to Heading, List, Image, and Paragraph only
* for users who do not have the 'publish_pages' capability.
*
* @param array|bool $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
* @param object $block_editor_context The current block editor context.
*
* @return array The array of allowed block types.
*/
function example_allowed_block_types_for_authors( $allowed_block_types, $block_editor_context ) {
// If the current user doesn't have the correct permissions, restrict blocks.
if ( ! current_user_can( 'publish_pages' ) ) {
$allowed_block_types = array(
'core/heading',
'core/image',
'core/list',
'core/list-item',
'core/paragraph',
);
return $allowed_block_types;
}
// The user has the correct permissions, so allow all blocks.
return true;
}
add_filter( 'allowed_block_types_all', 'example_allowed_block_types_for_authors', 10, 2 );
Refer to the Plugin Handbook for further information on checking roles and capabilities.
So far, we have not used the $block_editor_context parameter. This allows you to determine the characteristics of the Editor, such as the post type being edited, whether the user is working in the Editor or the Site Editor, and more.
Let’s modify the code to restrict the insertable blocks for all users when editing posts, but only if the user is in the Editor. All blocks should be enabled if editing other post types or working in the Site Editor.
For the post type slug, you can use $block_editor_context->post->post_type, and $block_editor_context->name will return the type of editor. Possible values are:
core/edit-post – Editor
core/edit-site – Site Editor
core/widgets – Widgets Editor
core/customize-widgets – Widgets Editor in the Customizer
/**
* Filters the list of allowed block types based on the editing context.
*
* This function restricts the available block types to Heading, List, Image, and
* Paragraph when the user is editing posts in the Editor. When editing other post types
* or in the Site Editor, all blocks are allowed.
*
* @param array|bool $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
* @param object $block_editor_context The current block editor context, including the editor type and the post being edited.
*
* @return array|bool The array of allowed block types when editing posts, or true to allow all blocks in other contexts.
*/
function example_allowed_block_types_when_editing_posts( $allowed_block_types, $block_editor_context ) {
// Only apply in the Editor when editing posts.
if (
'core/edit-post' === $block_editor_context->name &&
isset( $block_editor_context->post ) &&
'post' === $block_editor_context->post->post_type
) {
$allowed_block_types = array(
'core/heading',
'core/image',
'core/list',
'core/list-item',
'core/paragraph',
);
return $allowed_block_types;
}
// Allow all blocks in the Site Editor or when editing other post types.
return true;
}
add_filter( 'allowed_block_types_all', 'example_allowed_block_types_when_editing_posts', 10, 2 );
This approach can be helpful if your site utilizes custom post types designed to include only specific types of content.
Using a disallow list
Until now, we have provided a list of “allowed” blocks. While this works well in some situations, there are other scenarios where you might want to disable specific blocks instead. Perhaps your WordPress instance includes over a hundred blocks, and you wish to disable a few.
Implementing a “disallow” list requires a bit less code in JavaScript, which we will cover later in this article, but it still can be done in PHP using the allowed_block_types_all hook. The key here is to programmatically fetch all the available registered block types and remove the ones you want to disable.
Consider the following example to disable the Navigation and Query blocks for users who don’t have permission to edit_theme_options. Unless you have customized your WordPress installation, this will typically include only Administrators.
/**
* Filters the list of allowed block types based on user capabilities.
*
* This function checks if the current user has the 'edit_theme_options' capability.
* If the user does not have this capability, certain blocks are removed from the
* list of allowed block types in the Editor.
*
* @param array|bool $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
* @param object $block_editor_context The current block editor context.
*
* @return array The filtered list of allowed block types. If the current user does not have
* the 'edit_theme_options' capability, the list will exclude the disallowed blocks.
*/
function example_disallow_block_types( $allowed_block_types, $block_editor_context ) {
// If the current user doesn't have the correct permissions, disallow blocks.
if ( ! current_user_can( 'edit_theme_options' ) ) {
$disallowed_blocks = array(
'core/navigation',
'core/query',
);
// Get all registered blocks if $allowed_block_types is not already set.
if ( ! is_array( $allowed_block_types )
