block.json metadata

The block.json file simplifies defining and registering blocks by using the same JSON format to register the block on both the server and client (Block Editor).

Benefits of using block.json

Using a block.json file provides several benefits:

Performance: Block metadata is cached server-side, reducing overhead
Consistency: Same definition used for both server and client registration
Schema validation: JSON schema provides IDE autocomplete and validation
Tooling: Build tools can automatically detect and process blocks
Translation: Internationalization is handled automatically

Basic structure

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/my-block",
  "title": "My Custom Block",
  "category": "widgets",
  "icon": "smiley",
  "description": "A custom block for my site",
  "keywords": ["custom", "example"],
  "textdomain": "my-plugin",
  "attributes": {},
  "supports": {},
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

Basic metadata properties

API version

number

required

Specifies the Block API version. Use 3 for the latest version unless you have specific requirements.

Block name

string

required

The unique identifier for the block, including namespace (e.g., my-plugin/my-custom-block). Must contain a namespace prefix followed by a slash.

Display title

string

required

The display title shown in the Block Inserter and block editor interface.

Icon

string

default:"smiley"

Icon representing the block. Can be a Dashicon slug or custom SVG.

"icon": "heart"

Or with custom SVG:

"icon": "<svg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'><path d='M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z' /></svg>"

Description

string

A short description providing context beyond the title.

Keywords

array

Array of keywords to help users find the block when searching.

"keywords": ["gallery", "images", "photos"]

Text domain

string

The text domain for internationalization, typically matching your plugin slug.

File references

Specify the files that control block behavior and appearance:

Editor script

string|array

JavaScript file(s) loaded only in the Block Editor. Typically points to the bundled index.js.

"editorScript": "file:./index.js"

Editor style

string|array

CSS file(s) for styling within the Block Editor only.

"editorStyle": "file:./index.css"

Script

string|array

JavaScript file(s) loaded in both the Block Editor and front end.

Style

string|array

CSS file(s) applied in both the Block Editor and front end.

"style": "file:./style-index.css"

View script

string|array

JavaScript file(s) loaded solely on the front end.

"viewScript": "file:./view.js"

Render template

string

Path to a PHP template file for server-side rendering (dynamic blocks).

"render": "file:./render.php"

For file paths, use the file: prefix. You can also reference handles registered via wp_register_script or wp_register_style.

Block attributes

Attributes define data storage for the block:

"attributes": {
  "content": {
    "type": "string",
    "source": "html",
    "selector": "p"
  },
  "alignment": {
    "type": "string",
    "default": "left"
  },
  "showDate": {
    "type": "boolean",
    "default": true
  }
}

Attribute properties

type: Data type (string, number, boolean, array, object)
default: Default value if not set
source: How to extract value from saved content
selector: CSS selector for source extraction

Attributes are automatically serialized and stored in block delimiters by default.

Block supports

The supports property enables common features:

"supports": {
  "align": true,
  "color": {
    "text": true,
    "background": true,
    "link": true
  },
  "typography": {
    "fontSize": true,
    "lineHeight": true
  },
  "spacing": {
    "padding": true,
    "margin": true
  }
}

When using block supports, you must apply the generated attributes to your block wrapper using useBlockProps() in the edit component and useBlockProps.save() in the save function.

Complete example

Here’s a complete block.json for a copyright block:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/copyright",
  "title": "Copyright Date",
  "category": "widgets",
  "icon": "universal-access",
  "description": "Display copyright with date range",
  "keywords": ["copyright", "date", "footer"],
  "textdomain": "my-plugin",
  "attributes": {
    "fallbackCurrentYear": {
      "type": "string"
    },
    "showStartingYear": {
      "type": "boolean"
    },
    "startingYear": {
      "type": "string"
    }
  },
  "supports": {
    "color": {
      "text": true,
      "background": true
    }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

Get Started

Development Environment

Core Concepts

Block Development

Data & State

Guides

block.json metadata

Benefits of using block.json

Basic structure

Basic metadata properties

API version

Block name

Display title

Category

Icon

Description

Keywords

Text domain

File references

Editor script

Editor style

Script

Style

View script

Render template

Block attributes

Attribute properties

Block supports

Complete example

Next steps

Block attributes

Block supports

​Benefits of using block.json

​Basic structure

​Basic metadata properties

​API version

​Block name

​Display title

​Category

​Icon

​Description

​Keywords

​Text domain

​File references

​Editor script

​Editor style

​Script

​Style

​View script

​Render template

​Block attributes

​Attribute properties

​Block supports

​Complete example

​Next steps

Block attributes

Block supports

Benefits of using block.json

Basic structure

Basic metadata properties

API version

Block name

Display title

Category

Icon

Description

Keywords

Text domain

File references

Editor script

Editor style

Script

Style

View script

Render template

Block attributes

Attribute properties

Block supports

Complete example

Next steps