How to Create Custom WordPress Blocks Like a Pro

Key points:

• Learn three ways to create custom WordPress blocks: using basic plugins, manual coding with JavaScript, or ACF Blocks.
• Understand which approach best fits your project needs and technical skills.
• Follow a practical step-by-step guide to create your first custom block.
• See real examples of custom blocks in action.
• Save development time by choosing the right method for your situation.

WordPress tells you it’s flexible, but the second you need a custom block, that flexibility feels more like an obstacle course. Documentation is either buried in developer jargon or dumbed down to “install this plugin and hope for the best.” If you’re trying to build something real – something tailored to your needs – you’re left sorting through conflicting advice and half-explained solutions.

You’ve got three paths: You can go all-in with the WordPress Block API and the frontend framework React, give up all control to a plugin, or use Advanced Custom Fields (ACF®) to handle creating blocks in PHP. Each approach has tradeoffs, but ACF Blocks often hit the sweet spot between customization and efficiency, as well as giving content editors a simpler way to create layouts and add custom data.

This guide lays it all out – no vague tutorials, no unnecessary detours – so you can actually make an informed decision and build what you need without wasting time on the wrong tools.

Why create custom blocks in WordPress?

The default WordPress block editor works – until it doesn’t. You can try hacking together core blocks to fit your needs, but that’s just adding more work for yourself later. If you want structured layouts, branded components, or anything remotely custom, you need custom blocks.

Custom blocks are more than aesthetics; they define how content is structured, keeping your site maintainable and scalable.

Say you’re adding testimonials. Instead of relying on a generic text block and hoping no one breaks the formatting, a custom testimonial block locks in styling, enforces structure, and gives content creators a clear, intuitive interface.

Here are some benefits of custom blocks:

• Build exactly what you need instead of forcing generic blocks into your layout. Create blocks that fit your project’s specific requirements.
• Enforce consistent branding by locking in design elements so every block follows the same style, reducing inconsistencies across your site.
• Save development time with reusable blocks. This means less repetition, fewer headaches, and faster content updates.
• Keep content structured using well-defined blocks to prevent messy, inconsistent content that breaks your design over time.
• Make editing easier, with a more intuitive experience that reduces friction for non-technical users.

Choosing the right approach: 3 ways to create custom WordPress blocks

When you need custom blocks in WordPress, you’ve got three real options, each with its own mix of flexibility and frustration. You can dive into the Block API and a frontend framework, keep it barebones with a plugin or use ACF Blocks for a middle ground that won’t make you hate your life. The right choice depends on how much control you need and how much time you’re willing to spend wrestling with WordPress.

Let’s break it down.

1. Basic plugins

If you just need a quick custom block without touching too much code, plugins like Lazy Blocks get the job done. You get a visual interface, drag-and-drop controls, and some predefined components – perfect if you’re building simple content blocks.

The tradeoff is limited styling, minimal interactivity, and a rigid template system that can’t handle complex logic.

Here’s how it works:

1. Install Lazy Blocks from the WordPress plugin directory.
2. Go to Lazy Blocks > Add New, name your block, and define its structure.
3. Add fields like text, images, or buttons using the visual editor.
4. Set up a template for how the block should render on the front end.
5. Save, and it’s now available in the block editor.

This method is great for quick layouts but hits a wall fast if you need deep customization or dynamic content.

2. Manual coding

If you want full control over how your custom blocks work, look, and behave, you’re going to have to code them yourself. That means JavaScript, a framework like React or Svelte, and Node.js – no shortcuts.

WordPress provides some scaffolding tools, like @wordpress/create-block, but setting up a proper development environment still requires installing Node.js, configuring a local WordPress setup, and working inside a modern JavaScript stack.

If that already sounds exhausting, this might not be the method for you. Either way, here’s the basic process using React:

1. Install Node.js, your preferred code editor, and a local WordPress instance.
2. Use npx @wordpress/create-block my-block to generate the boilerplate structure.
3. Modify block.json to set up the block name, attributes, and category.
4. Write the React-based edit.js file to control how the block looks inside the editor.
5. Use save.js for static blocks or PHP for dynamic ones.
6. Add your block to WordPress, tweak as needed, and debug your JavaScript.

This is a high-level overview that lets you know what to expect. If it’s piqued your interest, switch over to a more detailed walkthrough. If not, consider ACF Blocks instead.

3. ACF Blocks: A powerful, low-code solution

If building blocks from scratch sounds like overkill but drag-and-drop plugins feel too limited, ACF Blocks is the middle ground that actually makes sense. It’s powerful, flexible, and – unlike JavaScript-heavy solutions – uses PHP and HTML, making it much easier for developers already familiar with WordPress theming.

You’ll need ACF PRO, but if you’re serious about custom blocks, it’s worth it.

Compared to basic block plugins, ACF Blocks integrates directly into the WordPress development ecosystem. The visual field builder allows you to quickly create structured, reusable blocks while still maintaining full control over the design and functionality.

Instead of wrestling with React, you’re working with a PHP-based templating system that fits into your theme development workflow. Agencies and solo developers love this because it speeds up development without sacrificing customization.

The numbers back it up: in 2024, 57% of WordPress developers using the block editor built blocks with ACF. That’s proof that ACF Blocks are often the better way to build.

Here’s a handy table to help you compare the three main options for creating custom blocks in WordPress:

Creating custom WordPress blocks with ACF PRO

To create your first custom block using ACF PRO, follow these steps:

1. In your (child) theme directory, create a folder for your custom block, e.g., /wp-content/themes/your-theme/blocks/my-custom-block/.
2. Create a block.json file in this folder, where you’re going to store standard block metadata and ACF-specific settings. Add the following code to it:

{
  "name": "acf/my-custom-block",
  "title": "My Custom Block",
  "description": "A custom block built with ACF.",
  "category": "formatting",
  "icon": "admin-customizer",
  "keywords": [ "custom", "acf" ],
  "supports": {
    "align": true,
    "multiple": true
  },
  "acf": {
    "mode": "preview",
    "renderTemplate": "blocks/my-custom-block/template.php"
  }
}

3. Create the block template in the same folder. For this walkthrough, we’ll call ours template.php, in line with what we specified in the JSON file above.
4. Inside the template, add your block’s content, e.g.:

<?php
/**
 * Custom Block template.
 *
 * @param array $block The block settings and attributes.
 */
?>
<div class="simple-text-block">
 <p>This is my custom block!</p>
</div>

5. Register the block with your (child) theme:

function my_register_blocks() {
    register_block_type( __DIR__ . '/blocks/my-custom-block' );
}
// Call the theme's register_acf_block() function on init.
add_action( 'init', 'my_register_blocks' );

Create a new post or page using the Gutenberg Editor and search for your custom block using the keywords specified in the JSON file. If you’ve done everything right, here’s what you should see:

Building advanced WordPress blocks with ACF PRO

The example above works well for static, reusable blocks like CTAs, but what if you need something more dynamic? Since ACF lets you capture custom data, let’s create a block that puts that data to use:

1. Create a new field group with fields for each team member’s name, role, and year they started.
2. Set the Location Rules to display the field group if Block is equal to your custom block.

3. Edit the template.php file to make it pull data from ACF:

<?php
/**
 * ACF Block Template - Tailwind-Style Card Component
 */

// Retrieve ACF fields
$name = get_field('name', $block['id']);
$role = get_field('role', $block['id']);
$year = get_field('year', $block['id']);
$photo = get_field('photo', $block['id']);

// Generate block ID and class
$block_id = isset($block['anchor']) ? esc_attr($block['anchor']) : 'acf-block-' . esc_attr($block['id']);
$block_classes = 'acf-custom-block ' . (!empty($block['className']) ? esc_attr($block['className']) : '');

?>
<div id="<?php echo esc_attr($block_id); ?>" class="<?php echo esc_attr($block_classes); ?>">
    <?php if (!empty($photo) && is_array($photo)): ?>
        <img src="<?php echo esc_url($photo['url']); ?>" alt="<?php echo esc_attr($name); ?>" class="team-photo">
    <?php endif; ?>
    <p class="team-member-name"><strong><?php echo esc_html($name); ?></strong></p>
    <p class="team-member-role"><?php echo esc_html($role); ?> since <?php echo esc_html($year); ?>.</p>
</div>

4. Edit the block.json and add "style": [ "file:./style.css" ] in the same section as the name, title, description, keywords, etc.
5. Create a style.css file in the same folder as block.json and template.php and add some styling that targets the class names you created in template.php:

/* Card container */
.acf-custom-block {
    background: #ffffff;
    border: 1px solid #e5e7eb; /* Light gray border */
    border-radius: 12px;
    padding: 20px;
    max-width: 320px;
    margin: 20px auto;
    text-align: center;
    font-family: Arial, sans-serif;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); /* Soft shadow */
    display: flex;
    flex-direction: column;
    align-items: center;
}

/* Profile photo */
.team-photo {
    width: 80px;
    height: 80px;
    border-radius: 50%;
    object-fit: cover;
    border: 4px solid #f3f4f6; /* Subtle border */
    margin-bottom: 15px;
}

/* Name styling */
.team-member-name {
    font-size: 1.2em;
    font-weight: bold;
    color: #111827; /* Dark gray */
    margin-bottom: 5px;
}

/* Role and year styling */
.team-member-role {
    font-size: 0.95em;
    color: #6b7280; /* Tailwind gray-500 */
}

6. Create a new post, add the block, and fill in the field data on the right:

7. Preview the post on the frontend, where you should see it in action:

ACF Blocks success story: Create, edit, and customize with ease

Sam Kent was just trying to make WordPress work for him – not reinvent it. His client’s outdated layout builder wasn’t built for Gutenberg, and rebuilding it from scratch in React wasn’t an option unless he wanted to double his timeline and budget. He needed a solution that worked with the tools he already knew.

ACF Blocks let him build customized reusable components using only the PHP he already knew and loved. With ACF’s PHP-based block system, Sam skipped the JavaScript-heavy workflow that slows down traditional block development. 

More importantly, ACF’s live preview and visual field builder meant his clients could edit their own content without breaking layouts. The result was a streamlined development process, fewer support requests, and a site that looked exactly as intended – without endless tweaks and revisions.

The efficiency was undeniable. Here’s how he put it:

“I can build a new block in about twenty minutes with the ACF plugin, depending on how complex the design is. More complex blocks will take one to two hours with ACF.”

That’s both fast and scalable. Instead of wasting time fighting the WordPress Block API, he spent it refining functionality, improving UX, and actually delivering projects on schedule.

Start building your first custom block today with ACF PRO

WordPress gives you plenty of ways to build custom blocks, but most of them come with tradeoffs. Most plugins are too limiting. Manual development is overkill unless you really need that level of control. ACF PRO sits in the middle, offering a PHP-based approach that keeps things fast, flexible, and familiar – without forcing you into a JavaScript rabbit hole.

Instead of reinventing how WordPress works, ACF PRO builds on what already makes sense. Its intuitive API and extensive documentation mean you’re not stuck parsing endless dependencies just to create a block that does what you want. Need something simple? It’s done in minutes. Complex? Extend it with familiar tools and keep full control without the extra bloat.

It’s all about making your development processes smarter. ACF PRO enables millions of developers to streamline their workflow, build better WordPress sites, and actually enjoy the process.

If you want custom blocks without unnecessary headaches, it’s time to start using ACF PRO – see what it can do for your site.