block.json

The block.json file simplifies the processs of defining and registering a block by using the same block’s definition in JSON format to register the block in both the server and the client.

Besides simplifying a block’s registration, using a block.json has several benefits, including improved performance and development.

At Metadata in block.json you can find a detailed explanation of all the properties you can set in a block.json for a block. With these properties you can define things such as:

• Basic metadata of the block
• Files for the block’s behavior, style, or output
• Data Storage in the Block
• Setting UI panels for the block

Basic metadata of the block

Through properties of the block.json, we can define how the block will be uniquely identified, how it can be found, and the info displayed for the block in the Block Editor. Some of these properties are:

• apiVersion: the version of the API used by the block (current version is 2).
• name: a unique identifier for a block, including a namespace.
• title: a display title for a block.
• category: a block category for the block in the Inserter panel.
• icon: a Dashicon slug or a custom SVG icon.
• description: a short description visible in the block inspector.
• keywords: to locate the block in the inserter.
• textdomain: the plugin text-domain (important for things such as translations).

Files for the block’s behavior, output, or style

The editorScript and editorStyle properties allow defining Javascript and CSS files to be enqueued and loaded only in the editor.

The script and style properties allow the definition of Javascript and CSS files to be enqueued and loaded in both the editor and the front end.

The viewScript property allow us to define the Javascript file or files to be enqueued and loaded only in the front end.

All these properties (editorScript, editorStyle, script style,viewScript) accept as a value a path for the file (prefixed with file:), a handle registered with wp_register_script or wp_register_style, or an array with a mix of both.

The render property (introduced on WordPress 6.1) sets the path of a .php template file that will render the markup returned to the front end. This only method will be used to return the markup for the block on request only if $render_callback function has not been passed to the register_block_type function.

Using attributes to store block data

Block attributes are settings or data assigned to blocks. They can determine various aspects of a block, such as its content, layout, style, and any other specific information you need to store along with your block’s structure. If the user changes a block, such as modifying the font size, you need a way to persist these changes. Attributes are the solution.

When registering a new block type, the attributes property of block.json describes the custom data the block requires and how they’re stored in the database. This allows the Editor to parse these values correctly and pass the attributes to the block’s Edit and save functions.

Example: Attributes as defined in block.json

"attributes": {
    "fallbackCurrentYear": {
        "type": "string"
    },
    "showStartingYear": {
        "type": "boolean"
    },
    "startingYear": {
        "type": "string"
    }
},

By default, attributes are serialized and stored in the block’s delimiter, but this can be configured.

Example: Atributes stored in the Markup representation of the block

<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->x

Reading and updating attributes

These attributes are passed to the React component Edit(to display in the Block Editor) and the save function (to return the markup saved to the database) of the block, and to any server-side render definition for the block (see the render property above).

The Edit component receives exclusively the capability of updating the attributes via the setAttributes function.

See how the attributes are passed to the Edit component, the save function and the render.php in this full block example of the code above

Enable UI settings panels for the block with supports

Many blocks, including core blocks, offer similar customization options, whether changing the background color, text color, or adding padding customization options.

The supports property in block.json allows a block to declare support for certain features, enabling users to customize specific settings (like colors or margins) from the Settings Sidebar.

Using the available block supports allows you to align your block’s behavior with core blocks and avoid replicating the same functionality yourself.

Example: Supports as defined in block.json

"supports": {
    "color": {
        "text": true,
        "link": true,
        "background": true
    }
}

The use of supports generates a set of properties that need to be manually added to the wrapping element of the block. This ensures they’re properly stored as part of the block data and taken into account when generating the markup of the block that will be delivered to the front end.

Example: Supports custom settings stored in the Markup representation of the block

<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
<!-- /wp:block-development-examples/block-supports-6aa4dd -->

See the full block example of the code above

Additional resources

• block.json diagram
• Attributes diagram