How to Build WordPress Blocks

Key points:

• Custom WordPress blocks enhance flexibility, reusability, and the editing experience, built using React or PHP with Advanced Custom Fields (ACF®).
• React-based blocks require setting up a plugin, configuring the settings, writing React components, and compiling scripts.
• ACF Blocks simplifies development using only PHP.
• Best practices include modular code, efficient data handling, accessibility compliance, and performance optimization for scalable block development.

Ever felt like the default WordPress blocks just don’t cut it? Maybe you need something more dynamic, more customized, or just better suited to your content workflow.

The good news is that you don’t have to settle for default blocks or overload your site with plugins. You can build your own WordPress blocks, tailor-made for your project.

There are two main ways to develop custom blocks, and each has its perks:

• React-based block development – the official way, using modern JavaScript tools. It’s flexible and powerful but has a learning curve.
• ACF Blocks – a simpler, PHP-based approach using Advanced Custom Fields (ACF®). It’s faster, easier to maintain, and perfect for teams who don’t want to mess with React.

We’ll walk you through both methods step by step to help you build scalable, high-quality WordPress blocks without the guesswork.

How to build a custom WordPress block

We’ll go over two main ways of creating a custom WordPress block: combining PHP with a frontend JavaScript framework – React in this case – and using ACF with PHP only.

Method 1. Using React

Building custom WordPress blocks with React gives you more control over the editing experience. It hooks into the WordPress data API for real-time updates, better state management, and interactive features.

This method works by building the block in JavaScript, allowing it to update live in the editor, then packaging and loading it into WordPress through a plugin so Gutenberg can use it.

Here’s how to do it:

Set up the development environment

1. Download and install WordPress locally using tools like Local, XAMPP, or a manual setup with Apache or Nginx and MySQL. This provides a controlled testing environment.
   
2. Download and install Node.js, which includes npm for managing JavaScript dependencies and running build tools.
   
3. Install WP-CLI to speed up development tasks like installing plugins, managing databases, and generating block scaffolds.
   
4. Configure a fresh WordPress installation in your local environment. Ensure debugging is enabled (WP_DEBUG in wp-config.php) and install the Gutenberg plugin if you’re testing the latest block editor features.

Initialize the plugin

1. Navigate to your WordPress installation and go to wp-content/plugins/. Create a new folder named my-custom-block.
2. Inside this folder, create a new PHP file named my-custom-block.php.
3. Add the following code to the file to register the plugin and load the block’s JavaScript file:

<?php
/*
 * Plugin Name: My Custom Block
 * Description: A simple custom Gutenberg block.
 * Version: 1.0
 * Author: Your Name
 */

// Enqueue block scripts
function my_custom_block_assets() {
    wp_enqueue_script(
        'my-custom-block-script',
        plugins_url('build/index.js', __FILE__),
        array('wp-blocks', 'wp-element', 'wp-editor'),
        filemtime(plugin_dir_path(__FILE__) . 'build/index.js')
    );
}
add_action('enqueue_block_editor_assets', 'my_custom_block_assets');

4. Open the WordPress admin panel, go to Plugins, find My Custom Block, and click Activate.

Configure the project

1. Open a terminal inside the my-custom-block plugin folder and run npm init -y to create a package.json file with default settings:
2. Run the following command to install the WordPress build tools:

npm install @wordpress/scripts --save-dev

3. Inside my-custom-block, create two new folders: src/ to hold the block’s source files, and build/, where compiled files are generated after running the build process.
4. Add the following code to package.json to run a development build with live reloading and generate the final production files:

"scripts": {
  "start": "wp-scripts start",
  "build": "wp-scripts build"
}

5. In the my-custom-block folder, create a block.json file and add the following code to define its metadata so it’s easier to register and maintain:

{
  "apiVersion": 2,
  "name": "myplugin/custom-block",
  "title": "Custom Block",
  "category": "widgets",
  "icon": "smiley",
  "editorScript": "file:./build/index.js"
}

Develop the block

1. Inside src/, create a new file named index.js. This will contain the block’s logic:

import { registerBlockType } from '@wordpress/blocks';
import { RichText } from '@wordpress/block-editor';

registerBlockType('myplugin/custom-block', {
    title: 'Custom Block',
    icon: 'smiley',
    category: 'widgets',

    edit({ attributes, setAttributes }) {
        return (
            <RichText
                tagName="p"
                value={attributes.content}
                onChange={(content) => setAttributes({ content })}
                placeholder="Enter your text here..."
            />
        );
    },

    save({ attributes }) {
        return <RichText.Content tagName="p" value={attributes.content} />;
    }
});

2. Add styling with a style.css inside the src folder (optional):

.wp-block-myplugin-custom-block {
    border: 1px solid #ddd;
    padding: 10px;
    font-size: 16px;
}

3. If you add a style.css, edit block.json to reference it:

"style": "file:./build/style.css"

4. Build the block using npm run build.

Verify that the block works by going into the Gutenberg editor and searching it up from the list.

Method 2. Using ACF Blocks

ACF Blocks provides an easier route to custom WordPress blocks by allowing you to use only PHP – no JavaScript or other frontend frameworks are needed.

It’s a premium feature of ACF PRO, and it allows you to pull in data from custom fields, making it the perfect tool for anyone who wants to build a truly bespoke WordPress website without the hassle.

Here’s how to create a custom block using ACF Blocks:

1. Create a blocks folder in your child theme’s folder and add a folder for your custom block. We’re going to call it custom-block.
2. Create a block.json file inside this folder and define the custom block’s settings:

{
  "name": "acf/custom-block",
  "title": "My Custom Block",
  "description": "A custom block that uses ACF fields.",
  "category": "layout",
  "icon": "admin-comments",
  "keywords": ["custom", "acf", "block"],
  "acf": {
    "mode": "preview",
    "renderTemplate": "template.php"
  },
  "supports": {
    "align": true
  },
  "textdomain": "custom-block",
  "editorScript": "file:./script.js",
  "editorStyle": "file:./editor.css",
  "style": "file:./style.css"
}

3. Create a render template with a template.php file inside blocks/custom-block:

<?php
// Get ACF field data (replace 'your_field_name' with the actual field name)
$data = get_field('your_field_name');
?>

<p>Your custom data is <?php echo esc_html($data); ?></p>

4. Register the block in the child theme’s functions.php:

<?php
function tt3child_register_acf_blocks() {
    register_block_type( __DIR__ . '/blocks/custom-block' );
}
add_action( 'init', 'tt3child_register_acf_blocks' );

5. Create a new custom ACF field using the name you specified in the template. In this case, it’s data.
6. Under Location Rules, assign it to display on your custom block, as shown below:

7. Open the block editor and search for the custom block. When it comes up, fill in the custom data’s meta box to verify that it works.

Business benefits of ACF Blocks

Here’s why ACF Blocks are the smarter choice over JavaScript-based development:

• Projects get delivered faster because ACF Blocks remove the need for complex JavaScript dependencies, letting developers build Gutenberg-compatible blocks with just PHP.
• Complex WordPress blocks require minimal coding since ACF Blocks provide a straightforward PHP-based workflow. Developers can create dynamic, feature-rich content structures without writing extensive JavaScript.
• Development costs stay lower by avoiding expensive React-based workflows. ACF Blocks eliminate the need for specialized front-end developers, making WordPress block development more budget-friendly.
• Development hours are reduced because there’s less need for custom JavaScript or React logic. ACF Blocks simplify block creation without dealing with framework updates, state management, or dependency conflicts.
• Team onboarding is easier since developers only need PHP and ACF knowledge. Without a React learning curve, new team members can contribute quickly without extensive training.
• Maintenance is simpler with ACF’s structured UI, which allows content teams and clients to make updates without risking layout or functionality issues.
• Technical debt stays low because ACF Blocks minimize reliance on custom-built solutions. There’s no need for ongoing JavaScript library updates or refactoring complex React-based code.
• Scaling across multiple projects is easier since ACF Blocks are reusable and easily adaptable. Developers and agencies can quickly replicate successful solutions without starting from scratch every time.

Best practices for developing custom WordPress blocks

Follow these development best practices so your custom WordPress blocks stand the test of time:

• Keep block code modular and reusable to improve readability, maintainability, and scalability. Separate, self-contained components ensure tidier code, easier debugging, and smoother updates across projects.
• Use render_callback in PHP for server-side dynamic content to securely process data and ensure accurate front-end rendering. This approach keeps sensitive logic out of JavaScript, enhances performance, and prevents client-side manipulation of critical data.
• Manage and sync data efficiently by using the WordPress REST API and @wordpress/data store. These tools help reduce unnecessary re-renders, keep content fresh, and optimize block performance by limiting redundant API calls.
• Ensure full accessibility compliance by following WCAG guidelines. Implement semantic HTML, proper ARIA roles, and keyboard navigation support to make your blocks usable for all visitors, including those relying on assistive technologies.
• Optimize performance by reducing block scripts and styles through lazy-loading assets and avoiding unnecessary dependencies. This improves page speed and user experience.
• Make blocks translation-ready by wrapping all user-facing text with __() or _x() functions from @wordpress/i18n to simplify localization efforts.

Build scalable custom WordPress blocks with ACF PRO

WordPress block development lets you create reusable, custom content blocks that make the editing experience smoother and more intuitive. Instead of relying on rigid page builders or wrestling with unpredictable layouts, custom blocks put complete control over design and functionality in your hands.

However, the traditional approach – diving into React, managing dependencies, and writing a mountain of JavaScript – adds complexity that slows down development and increases maintenance overhead.

With ACF Blocks, you can build powerful, dynamic blocks using just PHP – no React or other JavaScript frameworks. They also integrate with custom fields, making it easier to pull structured data into your blocks without extra code or API calls.

In the end, you get a more scalable, maintainable workflow that keeps projects running smoothly without technical debt piling up. For agencies, freelancers, and developers looking to simplify WordPress block development while maintaining flexibility, ACF Blocks offer a faster, more efficient solution.

Skip the complex React workflow and start building smarter with ACF PRO.