Extend Block Style Variations to Support Setting Block Settings

[mrwweb]

Block Style Variations have been a fabulous, easy, lightweight way to enable theme authors to give users access to interesting styles. However, there are times when the styles either overlap with or require being used in combination with other block settings.

For example, a button style might work best with a specific border radius or a Cover block style might only work with a fixed position background. A real-world example of this can be found in this support comment excerpted here:

We did consider also registering the style variation, but decided to proceed without it to start with. The reason being that by default the media & text block does not have a background color, and the image is not set to fill its column.

The pattern requires the image fill to make the text area overlap (tricky to get it to work efficiently without the background image fill), and looks a bit odd without a background color behind the text.

I believe this could be solved by support a third attributes parameter to register_block_style(). Some non-functional examples of what this might look like:

register_block_style(
    'core/button',
    array(
        'name' => 'awesome-button',
        'label' => 'Awesome Button',
    ),
    array(
        'border_radius' => 5,
    )
);

or this

register_block_style(
    'core/button',
    array(
        'name' => 'awesome-button',
        'label' => 'Awesome Button',
        'attributes' => array(
            'border_radius' => 5,
        )
    )
);

register_block_style(
    'core/media-text',
    array(
        'name' => 'cool-media-text',
        'label' => 'Cool Media & Text',
    ),
    array(
        'background' => 'has-primary-gradient-background',
        'color' => 'has-white-color',
        'fill_column' => true,
        'stack_on_mobile' => true,
    )
);

Alternatives Considered

Include all required styles in a single .is-style-... selector

This is a bad idea as some styles like background color or border radius may conflict with block settings, creating a very confusing user experience. At its most extreme, a theme author could make certain styles !important, thereby preventing a block setting from having any impact on a block's appearance.

Block Patterns

Block Patterns sort of solve this problem right now, but have a couple significant drawbacks.

1. They are not sorted/filtered by block type. This means the interface is significantly more likely to become cluttered if too many patterns are registered. With block styles, only relevant/applicable styles are shown for the block a user is currently editing.
2. Block Patterns, as the name implies, are intended for combinations of blocks and not selecting the appearance of a single block. Allowing users to apply complex styles to a single block is a great experience when that's all they want.

Fundamentally, Patterns and Style Variations serve different purposes. I believe that supporting the ability to specify block attributes as part of a defined style is consistent with the intent of the feature and likely to provide an even better user experience.

[mtias]

Hello! This is precisely the reason behind the full variations API, which seems like it would cover this use case pretty well. There's not much documentation, but can be checked here: #20581 and @richtabor also did a nice post https://richtabor.com/block-variations/

Block Variations generally allow to register a set of attributes for any block, including nested blocks. The variations can be exposed in the placeholder state (different defaults) or as their own block in the inserter through the API. There's a pending task for also exposing them in the sidebar after you have created a block.

[mrwweb]

Thanks for the reply, @mtias. I have to say that even after reading the Block Variations dev note in 5.4, this is the first time I really understand the feature and how it's intended to work. It seems there's a lot to be gained by improving the documentation and developer visibility of this feature.

One possible drawback that I think I saw confirmed in @richtabor's tutorial is that you can't register variations for Core blocks. There also seems to be a big focus on innerBlocks for variations as opposed to settings, but that may just be an issue of the examples I've seen.

Being able to provide preset configuration options (along with a custom class) for Core blocks is the primary goal of this request. If that means closing it in favor of another one, that's fine, so long as you can capture the real-world use cases.

[mtias]

Definitely a lot of room to improve the docs! The feature does work for any block, including core blocks (you can register a block variation for core/heading if you want). What made the impression that it wasn't possible? The focus is on any block attribute, with innerBlocks being just a supported extension of them.

[mrwweb]

What made the impression that it wasn't possible?

Going back, I realize now that I misread a comment in the tutorial. It seems like there's some additional stuff required to provide the UI like Columns has, but that doesn't mean the variations won't work without it. Thanks for the clarifications.

[mtias]

No worries! There's a ton of room to improve the documentation and communicate that this functionality does indeed exist, so thanks for the issue.

[mrwweb]

#25231 Addresses the request in this ticket for improving the UI for to allow for switching between block variations.

Given the register_block_pattern() and register_block_style() PHP functions, it seems like adding register_block_variation() would make a lot of sense to improve discoverability.

I also know people have mentioned the confusion between style variations and variations. If it were me, I'd rename to Block Styles and Block Configurations.

[mrwweb]

I'm closing this ticket since block variations meet this need. I do think a register_block_variation() PHP function would be awesome, but that can be a new ticket if needed.

I will say though that I still find that fairly experienced developers are still unaware of block variations.