How to lock blocks and templates

In this short lesson, I explain briefly what block locking is and when it is useful for site editing, and I describe techniques for locking blocks and templates.

Estimated reading time: 4 minutes

Last updated

March 21, 2024

What is block locking?
How to lock and unlock blocks in the editor
How to lock a single block in a template or pattern
How to lock multiple inner blocks
- Locking inner blocks in HTML files and patterns
- Locking templates for custom post types
How to prevent users from unlocking blocks
Resources

What is block locking?

The primary use for block locking is to prevent the accidental removal of important blocks or to prevent specific users from removing blocks. You can lock all WordPress core blocks and the experimental Gutenberg blocks. There are several types of locking available:

Block developers can lock inner blocks in their custom blocks using templateLock.
Theme and plugin developers can lock block templates with template_lock when registering or filtering a custom post type.

Theme developers can lock blocks by adding parameters to the JSON comment in the block markup. They can lock blocks in templates, template parts, and patterns.
Users can lock and unlock blocks in the editor, depending on their permissions.

With this type of locking, you can prevent users from:

Inserting blocks.
Removing blocks.
Moving blocks using drag or drop, arrow keys, or the list view.
Editing anything except text and media.

Note that a locked block can still have its style settings changed, for example

How to lock and unlock blocks in the editor

You can identify a locked block by the icon in the toolbar and in the list view:

To lock a single block, select the block and open the Options modal from the ellipsis menu in the block toolbar. Select the Lock menu item:

The lock option can be opened from the Options modal.

Select between lock all, disable movement, or prevent removal:

When the lock modal is opened, it has a heading that describes which block you have selected, and a form with 3 checkboxes: Lock all, disable movement, and prevent removal.
Below the checkboxes there is a cancel button and an apply button.

You can lock the inner blocks of container blocks like the group, cover, and columns. For these three blocks, there is a fourth option inside the block locking modal called “Apply to all blocks inside”:

When locking a group, the locking modal includes a toggle option with the label "Apply to all blocks inside".

How to lock a single block in a template or pattern

Theme developers can lock blocks with code in patterns, template parts, and templates.

The attribute you need to add to the block comment is called lock. Its options are:

move: Prevent users from moving a block (true or false).
remove: Prevent users from removing a block (true or false).

<!-- wp:heading {"lock":{"move":true,"remove":true}} -->
<h2>Heading two<br></h2>
<!-- /wp:heading -->

How to lock multiple inner blocks

To lock inner blocks, you need to use what is called a template lock:

templateLock is used inside HTML template files and block patterns.
template_lock is used when you want to lock a block template for a custom post type.

The template lock does not use true or false values; instead, its options are:

all: Prevent users from inserting new blocks and moving and removing blocks.
insert: Prevent users from inserting or removing blocks.
contentOnly: Only allow users to edit the content: text and media.

Locking inner blocks in HTML files and patterns

Theme developers can use templateLock as a block attribute for the group, cover, columns, column, and navigation blocks. These are the only supported core blocks.

<!-- wp:group {"templateLock":"all","lock":{"move":true,"remove":true}} -->
<div class="wp-block-group"></div>
<!-- /wp:group -->

Locking templates for custom post types

When you register a custom post type, you have the ability to register a block template. You can read more about this topic in the lesson “Creating templates for custom post types.”

template_lock is an argument in register_post_type():

function myplugin_register_book_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Books',
        'show_in_rest' => true,
        'template' => array(
            array( 'core/image', array(
                'align' => 'left',
            ) ),
            array( 'core/heading', array(
                'placeholder' => 'Add Author...',
            ) ),
            array( 'core/paragraph', array(
                'placeholder' => 'Add Description...',
                'lock' => array(
                    'move'   => true,
                    'remove' => true,
                 ),
            ) ),
        ),
        'template_lock' => 'insert',
    );
    register_post_type( 'book', $args );
}
add_action( 'init', 'myplugin_register_book_post_type' );

How to filter the template lock of an existing post type

To filter an already existing post type, you can update the template_lock on the $post_type_object. Please see the code example:

function myplugin_register_template() {
    $post_type_object = get_post_type_object( 'page' );
    $post_type_object->template = array(
        array( 'core/paragraph', array(
            'placeholder' => 'Add Description...',
        ) ),
    );
    $post_type_object->template_lock = 'all';
}
add_action( 'init', 'myplugin_register_template' );

Reminder:
lock locks a single block. templateLock locks inner blocks.

How to prevent users from unlocking blocks

To specify which user, user role, or capability should be able to lock and unlock blocks, you need to use the block_editor_settings_all filter. You can add this filter to your themes functions.php file.

The setting that you will be filtering is called canLockBlocks and accepts a true or false value:
True means that the user can lock and unlock blocks. False means that they can not lock or unlock. The default is true.

I have copied and edited the following example from the pull request by George Mamadashvili:

add_filter(
	'block_editor_settings_all',
	static function( $settings, $context ) {
		// Allow for the Editor role and above.
		$settings['canLockBlocks'] = current_user_can( 'delete_others_posts' );

		// Only enable for specific user(s).
		$user = wp_get_current_user();
		if ( in_array( $user->user_email, array( 'user@example.com' ), true ) ) {
			$settings['canLockBlocks'] = false;
		}

		// Disable for posts/pages.
		if ( $context->post && $context->post->post_type === 'page' ) {
			$settings['canLockBlocks'] = false;
		}

		return $settings;
	},
	10,
	2
);