Table of contents<\/strong><\/p>\n\n\n\n Block variations<\/strong> are a means to extend an existing block’s attributes<\/a> and inner blocks<\/a> to create a unique variation. <\/p>\n\n\n\n A common example of an existing WordPress block variation is the Embed block, which has numerous variations of the same functionality for embedding different providers, e.g. YouTube, Twitter, and Facebook. The Embed block leverages a custom Before we go any further, it is important to distinguish between block styles<\/strong> and block variations<\/strong>. Below is an overview of the differences.<\/p>\n\n\n\n Used to assign a custom selector (e.g. Used to extend an existing block’s attributes and even inner blocks.<\/p>\n\n\n\n It is possible to override the default block style by passing the Where block styles might be used to modify a block’s feel and appearance; block variations can do that and much more by modifying the substance of the block, and even its inner blocks.<\/p>\n\n\n\n Be careful with how many block variations you’re introducing. While the Embed block has dozens of block variations it can become unwieldy and you may want to consider creating a unique, new block if you’re introducing too many block variations to a core block.<\/p>\n\n\n\n Hopefully, that helps give you some guidance to choose between whether to customize a block with a variation<\/strong> or a block style<\/strong>.<\/p>\n\n\n\n Now let’s focus on how you can register, unregister, and even some common use cases for block variations.<\/p>\n\n\n\n You can pass the An object describing a variation defined for the block type can contain the following fields:<\/p>\n\n\n\n\n
\n
\n
\n
Overview of block variations<\/h2>\n\n\n\n
providerNameSlug<\/code> attribute to differentiate each embed’s icon and other attributes.<\/p>\n\n\n\n![\"Block](\"https:\/\/wpengine.com\/builders\/wp-content\/uploads\/embed-block-variations.png\")
Comparing block styles<\/mark> and block variations<\/mark><\/h2>\n\n\n\n
Block styles<\/strong><\/h3>\n\n\n\n
.is-style-blue-list<\/code>) and custom appearance to an existing block. Typically ideal if you need to just modify an existing block with some custom CSS.<\/p>\n\n\n\nPossible benefits<\/strong><\/h4>\n\n\n\n
\n
Possible downsides & pitfalls<\/strong><\/h4>\n\n\n\n
\n
\n
![\"Example](\"https:\/\/wpengine.com\/builders\/wp-content\/uploads\/image-block-styles-example.gif\")
Block variations<\/strong><\/h3>\n\n\n\n
className<\/code> attribute when creating a block variation.<\/p>\n\n\n\nPossible benefits<\/strong><\/h4>\n\n\n\n
\n
inserter<\/code>, block<\/code>, transform<\/code> (more on this below)<\/li>\n<\/ul>\n\n\n\nPossible downsides & pitfalls<\/strong><\/h4>\n\n\n\n
![\"Columns](\"https:\/\/wpengine.com\/builders\/wp-content\/uploads\/columns-block-variations.png\")
Adding block variations to a custom block<\/h2>\n\n\n\n
variation<\/code> object when a block is registered to assign an array of fields. Here is an example from the Embed block:<\/p>\n\n\nvariations: [\n<\/span><\/span> {\n<\/span><\/span> name<\/span>: 'wordpress'<\/span>,\n<\/span><\/span> isDefault<\/span>: true<\/span>,\n<\/span><\/span> title<\/span>: __( 'WordPress'<\/span> ),\n<\/span><\/span> description<\/span>: __( 'Code is poetry!'<\/span> ),\n<\/span><\/span> icon<\/span>: WordPressIcon,\n<\/span><\/span> attributes<\/span>: { providerNameSlug<\/span>: 'wordpress'<\/span> },\n<\/span><\/span> },\n<\/span><\/span> {\n<\/span><\/span> name<\/span>: 'google'<\/span>,\n<\/span><\/span> title<\/span>: __( 'Google'<\/span> ),\n<\/span><\/span> icon<\/span>: GoogleIcon,\n<\/span><\/span> attributes<\/span>: { providerNameSlug<\/span>: 'google'<\/span> },\n<\/span><\/span> },\n<\/span><\/span> {\n<\/span><\/span> name<\/span>: 'twitter'<\/span>,\n<\/span><\/span> title<\/span>: __( 'Twitter'<\/span> ),\n<\/span><\/span> icon<\/span>: TwitterIcon,\n<\/span><\/span> attributes<\/span>: { providerNameSlug<\/span>: 'twitter'<\/span> },\n<\/span><\/span> keywords<\/span>: [ __('tweet'<\/span>) ],\n<\/span><\/span> },\n<\/span><\/span>],\n<\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n\n
name<\/code> (type string<\/code>) \u2013 The unique and machine-readable name.<\/li>\n\n\n\ntitle<\/code> (type string<\/code>) \u2013 A human-readable variation title.<\/li>\n\n\n\ndescription<\/code> (optional, type string<\/code>) \u2013 A detailed variation description.<\/li>\n\n\n\ncategory<\/code> (optional, type string<\/code>) – A category classification, used in search interfaces to arrange block types by category.<\/li>\n\n\n\nicon<\/code> (optional, type string<\/code> | Object<\/code>) \u2013 An icon helping to visualize the variation. It can have the same shape as the block type.<\/li>\n\n\n\nisDefault<\/code> (optional, type boolean<\/code>) \u2013 Indicates whether the current variation is the default one. Defaults to false<\/code>.<\/li>\n\n\n\nattributes<\/code> (optional, type Object<\/code>) \u2013 Values that override block attributes.<\/li>\n\n\n\ninnerBlocks<\/code> (optional, type Array[]<\/code>) \u2013 Initial configuration of nested blocks.<\/li>\n\n\n\nexample<\/code> (optional, type Object<\/code>) \u2013 Example provides structured data for the block preview. You can set to undefined<\/code> to disable the preview shown for the block type.<\/li>\n\n\n\nscope<\/code> (optional, type WPBlockVariationScope[]<\/code>) – the list of scopes where the variation is applicable. When not provided, it defaults to block<\/code> and inserter<\/code>. Available options:\n