New: the block variations API

Just as you can declare a block’s style variations when you register a block, a block type can define block variations the user can pick from. The difference is that, beyond changing the look, this field offers a way to apply initial custom attributes and inner blocks at the point of insertion.

By default, all the variations will show up in the Inserter along with the regular block-type item. But you can set the isDefault flag for any of the listed variations—and in the process, you’ll override the regular block type in the Inserter.

variations: [
    {
        name: 'wordpress',
        isDefault: true,
        title: __( 'WordPress' ),
        description: __( 'Code is poetry!' ),
        icon: WordPressIcon,
        attributes: { service: 'wordpress' },
    },
    {
        name: 'google',
        title: __( 'Google' ),
        icon: GoogleIcon,
        attributes: { service: 'google' },
    },
    {
        name: 'twitter',
        title: __( 'Twitter' ),
        icon: TwitterIcon,
        attributes: { service: 'twitter' },
    },
],

An object describing a variation defined for the block type can contain these fields:

  • name (type string) – The unique and machine-readable name.
  • title (type string) – A human-readable variation title.
  • description (optional, type string) – A detailed variation description.
  • icon (optional, type String | Object) – An icon helping to visualize the variation. It can have the same shape as the block type.
  • isDefault (optional, type boolean) – Indicates whether the current variation is the default one. Defaults to false.
  • attributes (optional, type Object) – Values that override block attributes.
  • innerBlocks (optional, type Array[]) – Initial configuration of nested blocks.
  • example (optional, type Object) – Example provides structured data for the block preview. You can set to undefined to disable the preview shown for the block type.
  • scope (optional, type String[]) – the list of scopes where the variation is applicable. When not provided, it assumes all available scopes. Available options: block, inserter.

#5-4, #block-editor, #dev-notes