Building WordPress Custom Blocks with block.json (WP JSON) in the UK
16 August 2026
Learn to build WordPress custom blocks using block.json. A practical UK-focused guide covering registration, React, accessibility and performance in 2026.
Why block.json Is the Backbone of Custom Gutenberg Blocks
Since WordPress 5.8, block.json has become the standard way to define custom blocks. This single JSON file centralises metadata: block name, title, attributes, supports, and even editor scripts. For UK developers, this means cleaner code, easier maintenance, and better collaboration across teams. Using block.json aligns with modern WordPress practices and ensures your custom blocks work seamlessly with future updates. It also simplifies internationalisation, allowing you to set text domains for UK English or other locales. In 2026, WordPress continues to push the block system forward, so adopting block.json now positions your projects for long-term stability and scalability.
Setting Up a Custom Block Plugin: A Step-by-Step Guide
Start by creating a plugin folder under wp-content/plugins, e.g., uk-custom-blocks. Inside, create a main PHP file with a plugin header, and a build directory for compiled assets. Your block.json lives in the block folder, defining the block name like 'uk/example-block'. Use the official @wordpress/create-block package to scaffold the project quickly; it generates the correct file structure and build process. For UK-based developers, ensure your plugin follows WordPress coding standards and include a README with clear installation instructions. This approach reduces setup time and avoids common pitfalls, letting you focus on functionality rather than configuration.
Registering Blocks in PHP: Using wp_json_file and Metadata
In PHP, you register a block by calling register_block_type() and passing the path to block.json. WordPress reads the JSON file and handles asset enqueuing automatically. The function references the scripts and styles declared in the 'editorScript' and 'style' properties. Make sure your block.json includes 'apiVersion' (use 3 for latest), 'textdomain' for translations, and 'supports' for features like alignment and custom classes. For UK sites, remember to set the 'textdomain' to match your plugin's domain so translation files load correctly. This metadata-driven approach reduces boilerplate code and makes your blocks consistent across different projects.
Building the Editor UI with JavaScript and React
A custom block's editor interface is built with React, wrapped by WordPress's block API. Your main JS file uses registerBlockType() or a block.json-driven registration via @wordpress/blocks. You'll define the edit and save functions using JSX. For UK developers, prioritise accessibility in the editor: use focusable controls, proper ARIA labels, and keyboard navigation. Also consider integrating with the block inspector for settings. Since 2026, WordPress encourages using the Block Library and components for consistent UX. Make sure your code is transpiled with wp-scripts, which handles JSX, and enqueues only the needed dependencies to keep the admin area fast.
UK-Specific Considerations: Accessibility, GDPR and Performance
When building custom blocks for UK clients, follow the Equality Act 2010 by ensuring your blocks are accessible to all users. Use semantic HTML, ensure colour contrast meets WCAG 2.2 AA standards, and test with screen readers. GDPR compliance means avoiding embedding data from third parties without consent; if your block loads an iframe (e.g., a map), add a placeholder. Performance is critical for Core Web Vitals - lazy-load scripts and inline small assets. Also, British English spelling ('colour', 'organisation') should be used in user-facing text. By considering these factors, you'll deliver robust, compliant, and fast websites that serve the UK market effectively in 2026.
FAQ
block.json is a JSON file that stores metadata about a custom Gutenberg block, including its name, title, attributes, scripts, styles, and supports. Introduced in WordPress 5.8, it standardises block registration and lets WordPress automatically enqueue required assets. This makes blocks easier to maintain and share, and it's now the recommended way to author custom blocks.