Repository navigation
bug:theme.json controls core/cover overlay opacity via settings.color.defaultGradients #54140
Description
Description
I don't know if it is supposed to work like this but i found it unintuitive.
If i disable the entire settings.color property, (not settings.blocks.core/cover.color) to prevent color usage this cause the core/cover to lose abilty to control the overlay opacity.
Trying to reenabling it, it is necessary to enable settings.blocks.core/cover.color.defaultGradients.
It doesn't make sense for me.
Step-by-step reproduction instructions
- Use this theme json
{
"version": 2,
"$schema": "https://schemas.wp.org/trunk/theme.json",
"settings": {
"color": {
"defaultPalette": false,
"defaultDuotone": false,
"defaultGradients": false,
"custom": false,
"customDuotone": false,
"customGradient": false,
"background": false,
"link": false,
"text": false,
"palette": []
},
"blocks": {
"core/cover": {
"appearanceTools": false,
"color": {
"defaultGradients": true
}
}
}
},
}
- Check that overlay opacity control is not present in
core/cover - Add
{
"version": 2,
"$schema": "https://schemas.wp.org/trunk/theme.json",
"settings": {
"color": {
"defaultPalette": false,
"defaultDuotone": false,
"defaultGradients": false,
"custom": false,
"customDuotone": false,
"customGradient": false,
"background": false,
"link": false,
"text": false
},
"blocks": {
"core/cover": {
"color": {
"defaultGradients": true
}
}
}
}
}
- Check that overlay control is now present
Screenshots, screen recording, code snippet
No response
Environment info
- Wordpress 6.3.1
- NO Gutenberg Plugin
Please confirm that you have searched existing issues in the repo.
Yes
Please confirm that you have tested with all plugins deactivated except Gutenberg.
Yes
Activity
ndiego commentedon Sep 5, 2023
Thanks for reporting @tresorama. This is a tricky bug. The overlay slider is part of the Color supports panel in the Setting Sidebar. When all the color controls are disabled, so is the Color support panel, which also causes the slider to be hidden.
This is a larger issue for those wanting to extend Core block support panels. It's almost like we need a check to see if other controls should be displayed, even if those controlled in theme.json are hidden. 🤔
cc @Mamaduka @aaronrobertshaw
tresorama commentedon Sep 5, 2023
This is what i thought when i'm dealing with it.
But if i remember well, not every
settings.blocks.core/cover.color.XXXXXre-enables the color panel ( causing opacity control to be present ).I tried each of those one by one and the first that worked is
defaultGradients, so I stopped there, but maybe also others do the same.It would be good to check all of them.
Or detach "overlay" related controls to dedicated
settings.color.overlayColorsettings.color.overlayOpacity...aaronrobertshaw commentedon Sep 6, 2023
Thanks for the ping 👍
From memory, the overlay opacity was thought of as essentially part of the overlay color. It's effectively a shortcut to adjusting the color's alpha. If all color support is disabled, so to then was the overlay, which in turn affects the opacity control.
The disabling of color support and the related panel is very awkward. No arguments here. It prompted me a while back to try and outline all the inconsistencies with disabling block support UIs. Unfortunately, I haven't had the bandwidth to address any of the tasks outlined in that issue.
Personally, I'd probably lean towards keeping the tight coupling between the overlay color and its opacity. It's not a position I hold strongly though if there proves to be a demand for doing the opposite.
You can find some further history and context in previous issues and PRs.
You can see in the Cover block's inspector controls where the overlay and overlay opacity controls are conditionally rendered. That condition is based on
useMultipleOriginColorsAndGradientswhich determines whether the block has any colors or gradients.I believe the block support panels, e.g color, typography etc, will show if there are any fills to render into them. It's why the issue linked above was raised when the thinking was that the overlay and opacity shouldn't be shown if colors were disabled.
It is the cover block itself that omits the overlay controls from the panel not the panel or theme.json themselves. The theme.json settings are using by the block in making that determination though.
Given overlay isn't a feature within color block supports, I don't think this is a viable option. It's an ad hoc control added by the Cover block which doesn't apply to other blocks adopting color support.
IIRC there has been some discussion in the past around allowing bespoke settings per block-type in the theme.json. It might have been around allowing button width to be disabled. If that feature was added, it might provide the mechanism to control display of ad hoc block controls.
Hopefully, that helps provide a clearer picture of our current situation.
Ultimately, I'm not sure if we can describe this as a bug. It might be best pivoted into a feature request for a different approach. What do you all think?
youknowriad commentedon Aug 27, 2026
Closing as answered: as explained in-thread, the overlay opacity is deliberately part of the color support (it's the overlay color's alpha), so disabling all color settings hides it too — unintuitive at first sight but consistent with the support model. A docs note on the Cover block's settings would be a fine follow-up. Thanks!
aaronrobertshaw commentedon Aug 31, 2026
I've put up a quick PR updating the Cover block docs in #82234.
Docs: Explain when the Cover block's overlay controls appear