Cover Block: Add filter to disable automatic overlay color selection

[Mustafabharmal]

What?

Adds a new JavaScript filter blocks.cover.autoSetOverlayColor to allow disabling the automatic overlay color selection in the Cover block.

Why?

Fixes #60644

When an image is selected for the Cover Block, the overlay color automatically changes to a representative color from the image. This poses issues for users who:

1. Need to enforce strict color palettes - the automatic selection bypasses approved color restrictions
2. Prefer consistent overlay colors (like black or white) regardless of the selected image
3. Want full control over overlay color selection without automatic changes

How?

• Added a new JavaScript filter blocks.cover.autoSetOverlayColor (defaults to true for backward compatibility)
• Applied the filter check in three locations where automatic color selection occurs:
  • useEffect for featured image changes
  • onSelectMedia when media is selected
  • toggleUseFeaturedImage when toggling featured image
• Added comprehensive documentation in /docs/reference-guides/filters/editor-filters.md

Usage Example

import { addFilter } from '@wordpress/hooks';

// Disable automatic overlay color selection
addFilter(
    'blocks.cover.autoSetOverlayColor',
    'my-plugin/disable-cover-auto-color',
    () => false
);

Testing Instructions

Test automatic color selection still works (default behavior)

1. Create a new post
2. Add a Cover block
3. Select an image with distinct colors (e.g., a blue sky image)
4. Verify the overlay color automatically changes to match the image's average color
5. Try with different images and verify the overlay color updates each time

Test disabling automatic color selection

1. Add this code to a plugin or your theme's functions.php:

add_action( 'enqueue_block_editor_assets', function() {
    wp_add_inline_script( 'wp-blocks', "
        wp.hooks.addFilter(
            'blocks.cover.autoSetOverlayColor',
            'test/disable-auto-color',
            function() { return false; }
        );
    " );
} );

2. Create a new post
3. Add a Cover block with a background color (e.g., black)
4. Select an image
5. Verify the overlay color remains unchanged (stays black)
6. Try changing images - the overlay should not change automatically
7. Manually change the overlay color - verify it works as expected

Screenshots or screencast

Default Behaviour: (i.e: when 'blocks.cover.autoSetOverlayColor' is set to true)

Screen.Recording.2026-01-29.at.2.40.04.AM.mov

No Overlay Behaviour (i.e: when 'blocks.cover.autoSetOverlayColor' is set to False)

Screen.Recording.2026-01-29.at.2.42.26.AM.mov

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Mustafabharmal <[email protected]>
Co-authored-by: hagege <[email protected]>
Co-authored-by: MadtownLems <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.