Build Powerful ACF Custom Blocks That Load in Under 300ms

Alexandra

Employee Experience (EX) Manager, WPRiders

Published: July 22, 2025

TL;DR

This guide shows you how to build custom WordPress blocks using Advanced Custom Fields (ACF) Pro—entirely in PHP—without React. You’ll learn to plan, implement, and optimize ACF blocks that load in under 300ms, follow WordPress standards, and offer seamless backend editing. Includes real code, performance tips, and benchmarks.

Introduction

ACF custom blocks are a major upgrade for WordPress developers who think in PHP, prefer simplicity, and care about performance. Instead of wrestling with React, JSX, and complex JavaScript build tools, ACF Pro lets you build custom Gutenberg blocks using the tools you already know—PHP, HTML, and smart templating.

Whether you’re running an agency, working on client projects, or maintaining your own high-performance site, ACF blocks let you create reusable, dynamic content components that integrate seamlessly with the WordPress editor. And the best part? You can do it all without ever leaving the PHP world.

This guide is for developers who want their blocks to be fast (we’re talking under 300ms), maintainable, and editor-friendly. You’ll learn how to:

• Plan your block architecture around content reuse
• Set up block.json and ACF’s local JSON for speed
• Use PHP templates to build and preview blocks
• Optimize field usage and avoid common bottlenecks
• Measure performance using real benchmarks

If you’re tired of slow blocks, bloated builds, or endless JavaScript configs—this guide will show you a better, faster, and leaner way to build in WordPress.

Let’s dive in.

Why Choose ACF for Custom Gutenberg Blocks?

Advanced Custom Fields Pro enables you to register and render blocks using PHP templates. This allows for faster development cycles, reduced build complexity, and a more familiar experience for backend-focused WordPress developers.

Benefits:

• PHP-first workflow — No JSX, Webpack, or Babel required
• Faster iteration — Use get_field() and have_rows() in templates
• Block editor integration — Native look and feel for editors
• Modular by design — Scales well for large content systems

Sample Registration:

add_action('acf/init', function () {
    acf_register_block_type([
        'name'            => 'testimonial',
        'title'           => __('Testimonial'),
        'render_template' => 'blocks/testimonial/template.php',
        'category'        => 'formatting',
        'icon'            => 'format-quote',
        'keywords'        => ['quote', 'testimonial'],
    ]);
});

Requirements

• ACF Pro v6.2 or higher
• WordPress 5.8+
• Custom theme with support for block.json
• PHP 7.4+

ACF vs Native WordPress Blocks

Planning a Strategic ACF Block Development Workflow

Step 1: Audit Your Content

Look for content patterns: testimonials, service grids, bios. Identify repeatable structures.

Step 2: Choose Implementation Type

• ACF Blocks: PHP logic, complex fields, tight backend control
• Native Blocks: Live previewing, collaborative editing
• Block Patterns: Simple, layout-based sections

Step 3: Define Performance Goals

Use tools like PageSpeed Insights or performance.now() in browser dev tools.

Suggested Targets:

• First Contentful Paint (FCP): < 1.5s
• Largest Contentful Paint (LCP): < 2.5s
• Time to Interactive (TTI): < 3s
• Individual ACF block render time: < 300ms

Setting Up ACF Custom Block

Directory Structure

/your-theme/
  ├── /blocks/
  │    └── /my-custom-block/
  │         ├── block.json
  │         ├── template.php
  │         └── style.css
  └── /acf-json/

Sample block.json

{
  "name": "acf/my-custom-block",
  "title": "My Custom Block",
  "acf": {
    "renderTemplate": "blocks/my-custom-block/template.php"
  },
  "style": ["file:./style.css"],
  "supports": {
    "spacing": { "margin": ["top", "bottom"], "padding": true },
    "color": { "background": true, "text": true }
  }
}

Load Block in functions.php

function my_register_blocks() {
    register_block_type(__DIR__ . '/blocks/my-custom-block');
}
add_action('init', 'my_register_blocks');

Template Example

<?php
$name = get_field('name');
if ($name):
    echo '<h2>' . esc_html($name) . '</h2>';
endif;

if (have_rows('features')): ?>
    <ul>
        <?php while (have_rows('features')): the_row(); ?>
            <li><?php the_sub_field('label'); ?></li>
        <?php endwhile; ?>
    </ul>
<?php endif; ?>

Secure Output

• Use esc_html(), esc_attr()
• Validate conditionals to avoid template warnings

Performance Optimization for ACF Blocks

Use Local JSON

Store field group config in /acf-json/ to avoid DB queries.

Paginate Repeaters

Use paginated UI if blocks load many repeated fields.

Lazy Load Assets

Only enqueue CSS/JS when the block is rendered.

Example: Inline Render Time Logging

<?php
$start = microtime(true);
// your block render code
$end = microtime(true);
echo "<!-- Rendered in " . ($end - $start) . " seconds -->";
?>

Measuring Performance

Bottlenecks to Watch For

• Large nested Repeaters or Flexible Content
• Complex get_field() chains
• Too many conditional logic fields
• Unoptimized image fields

Data Flow Diagram

Understanding the internal flow helps in debugging and optimizing ACF custom blocks:

1. block.json
   ↓
2. acf_register_block_type()
   ↓
3. render_template.php (via acf/init)
   ↓
4. get_field() / have_rows()
   ↓
5. Escaped and sanitized output (HTML)
   ↓
6. Editor + Frontend Render

Detailed Explanation:

• block.json: Provides metadata and structure for the block (title, icon, supports, template path).
• acf_register_block_type(): Hooked into acf/init, registers the block server-side with ACF.
• render_template.php: A PHP file that receives $block, $content, $is_preview, and $post_id as variables.
• get_field() / have_rows(): Fetches ACF field values tied to the block’s post_id or context.
• Escaped HTML: Data is processed and escaped using esc_html(), esc_attr() before being printed.
• Editor + Frontend Render: Block is rendered both in the backend block editor and on the frontend using the same PHP template, ensuring WYSIWYG accuracy and performance.

FAQs

Is ACF Pro required?

Yes, ACF custom blocks are exclusive to the Pro version.

Can ACF blocks support native editor controls?

Yes, define supports in block.json to enable margin, padding, and color pickers.

Are ACF blocks future-proof?

As long as ACF Pro is maintained (active since 2011), blocks built with it will remain compatible. Use clear templating and best practices.

Can I use JavaScript with ACF blocks?

Yes. While ACF blocks are PHP-driven, you can enqueue block-specific JS and CSS files conditionally when rendering the block.

How can I test ACF block performance?

Use inline microtime(true) benchmarking in your templates, browser dev tools, or plugins like Query Monitor to measure block rendering speed.

What are common pitfalls to avoid?

Avoid overloading blocks with deeply nested repeaters or unpaginated media fields. Keep logic clean and avoid unnecessary database calls in templates.

???? Key Takeaways

• ACF Pro is required to create custom blocks via PHP templating.
• No React or build tools needed—just get_field(), block.json, and smart templating.
• Faster dev cycle for PHP-focused teams, ideal for agencies or fast-paced projects.
• Supports native editor controls like padding, margin, and colors with block.json.
• Use ACF Local JSON to reduce DB load, paginate Repeaters, and lazy-load assets.
• Target <300ms block render time, TTFB < 200ms, and LCP < 2.5s.
• Plan content structure in advance—use ACF Blocks only where needed, and use Block Patterns or native blocks when more efficient.
• Measure real-world render times with microtime(true) and audit bottlenecks like nested fields or image queries.

In Conclusion

ACF custom blocks are a fast, developer-friendly way to build scalable WordPress content systems. With a focus on PHP, modular design, and performance, they offer an excellent alternative to React-based block development.

Start lean. Think modular. Measure everything.

And keep your blocks under 300ms.

Do you like this article? Share it and send us your feedback! Check out our articles page, where you might find other interesting posts. Also, if you want to learn more about business, check out the WPRiders Blog!

Don't forget to subscribeReceive WPRiders' newsletter for the freshest job openings, sent directly to your inbox. Stay informed and never miss a chance to join our team!

Email Address*

Name

I accept the terms and conditions