Skip to content

Extensions

Extensions allow you to extend any registered block in your WordPress installation using a simple .json based API, which is similar to the block.json configuration. This includes core, third-party and blocks made with Blockstudio.

All field types can be added to any block, with the data being saved to the block’s attributes. The complete feature set of attributes like filtering, disabling, conditional logic and populating options are available for extensions.

Extension Types

Extended values can be utilized in versatile ways:

  • class: Add a class using the attribute value to the block
  • style: Add inline styles using the attribute value to the block
  • attributes: Set any attribute value directly on the block
  • data attributes: Use extension values to set specific data attributes

Setup

Imagine the following scenario: you want to add a custom class select field to every core block. All you need to do is add this .json file anywhere in your block folder, and it will be automatically registered as an extension.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

This will add a customColor field to every core block, allowing you to set the color of the block’s text.

File Name

Since there is no rendering template, an extension doesn’t need a matching index file and thus doesn’t need to be named block.json. This allows storing all extensions conveniently in a single folder. Several files may extend the same blocks, for example two files with "name": "core/*"; each registers its own fields.

Schema

Blockstudio provides a custom JSON schema for extension configurations:

View Extension schema

Name

The name property of the configuration object defines which blocks should be extended. There are three options depending on your needs:

  • blockName: A single block name, e.g. core/paragraph
  • [blockNameA, blockNameB]: An array of block names, e.g. ["core/paragraph", "core/heading"]
  • core/*: A wildcard to extend all blocks of a certain type

Any name that ends in an asterisk is a prefix wildcard, not only core/*. The following extension applies to every block whose name starts with my-plugin/, including blocks made with Blockstudio:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Excluding Blocks

Use a top-level exclude array to skip blocks that would otherwise match name:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Exclusions use the same exact-name and trailing-* prefix matching as name. They take precedence over single names, name lists, and wildcards. An excluded block receives neither the extension’s editor fields nor its frontend attributes or assets. Other matching extensions are unaffected. Omit exclude or use an empty array to keep the existing behavior.

Blockstudio Key

Just like when using block.json for custom blocks, the blockstudio property has to be present in the configuration object with extend set to true.

Position

By default, extensions will render in its own tab in the block inspector. If you want to move the extensions to a different position, you can use the group property:

  • settings: The default position
  • styles: The styles tab
  • advanced: The advanced tab
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Priority

The priority property allows you to define the order in which extensions are rendered. Extensions with a higher priority will be rendered later. Set it at the top level of the file, as in the setup example, or inside extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

When both are set, blockstudio.extend.priority wins.

Attributes

For more information on how attributes work, please refer to the attributes section.

The only thing you need to know about attributes inside extensions is the set property. It is used to apply the value of the attribute to one of the extension types.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Getting Values

Dot notation inside curly braces is used to get the value of an attribute.

It is also possible to get nested values when attributes are not returning a single value, for example, when setting the return format to both on field types with options.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

The example above will set the style attribute to color: #f00 or color: #00f and the data-color attribute to Red or Blue depending on the value.

For now, only values from the current attribute can be used inside set definitions. The ability to use values from other attributes might be added in the future.

Arrays

When using arrays, the set property will be applied to every item in the array.

Each item adds its own class or style declaration. Any other attribute holds a single value, so every item overwrites it and the last item wins. Set join to true to write the results of all items instead, separated by spaces and without empty or repeated values, so a selector like [data-langs~="en"] matches every chosen item. join has no effect on class and style, or on fields that return a single value.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

Choosing both options renders data-langs="en de". Without join, it renders data-langs="de".

Attributes Field

When using the attributes field, there is no set property needed, as the field automatically maps the values to the attribute name and value.

Inspecting Extension Fields

bs_block_extension_fields('core/paragraph') returns the field definitions of every extension that matches a block. See Inspecting Blocks for the return value and how it relates to bs_block_fields().