ACF Blocks Plugin

A comprehensive WordPress plugin that provides a collection of reusable, customizable ACF Pro blocks for the block editor. Uses ACF Block Version 3 with automatic field group registration.

Features

• Plugin Architecture: Standalone WordPress plugin - no theme modifications required
• Automatic Field Groups: Field groups are registered automatically from JSON - no manual imports needed
• Modern Block Registration: Uses ACF Block v3 with block.json metadata
• Zero-JavaScript Accordions: Uses native HTML <details>/<summary> elements for accordion blocks
• Conditional Asset Loading: CSS and JS only load when blocks are actually used on the page
• Performance Controls: Disable unused blocks, inspect block usage, and generate a lean site-specific editor stylesheet
• Optional Semantic Defaults: Add zero-specificity fallback styles inside a shared .acf-block wrapper for themes with incomplete content styling
• Background Processing: Image localization and large content migrations run in bounded resumable jobs
• Modular Architecture: Each block is self-contained with its own template, styles, and configuration
• ACF Pro Compatible: Requires ACF Pro 6.0+ for full functionality

Requirements

• WordPress 6.0+
• PHP 7.4+
• Advanced Custom Fields Pro 6.0+

Installation

1. Download the plugin and upload to wp-content/plugins/acf-blocks-plugin/
2. Activate the plugin through the WordPress admin
3. Ensure ACF Pro is installed and activated
4. Start using blocks in the block editor!

No additional configuration required - field groups are automatically registered.

Available Blocks

Content Blocks

• Accordion Block (acf/accordion) - Collapsible content for FAQs and disclosure sections (searchable by "FAQ")
• Testimonial Block (acf/testimonial) - Customer testimonials with ratings
• Hero Block (acf/hero) - Hero section with headline, image, and CTA
• CTA Block (acf/cta) - Call-to-action with heading and button
• Callout Block (acf/callout) - Highlighted callout boxes
• Opinion Box (acf/opinion-box) - Editorial content with author

Product & E-Commerce

• Product Review (acf/product-review) - Reviews with star ratings and schema
• Product Cards (acf/product-cards) - Product showcase cards
• Product Box (acf/product-box) - Single product display with CTA buttons
• Coupon Code (acf/cb-coupon-code) - Promotional code display with copy feature
• Compare Block (acf/compare) - Side-by-side comparisons
• PL Block (acf/pl-block) - Product lists with pricing

Media & Display

• Video Block (acf/video) - Video embeds
• Gallery Block (acf/gallery) - Image galleries
• Stats Block (acf/stats) - Statistics display
• Star Rating (acf/star-rating) - Interactive ratings with atomic storage and a public REST endpoint

Navigation & Organization

• Tabs Block (acf/tabs) - Tabbed content with multiple styles
• Feature Grid (acf/feature-grid) - Grid layout for features
• Section Block (acf/section-block) - Container wrapper with InnerBlocks
• Post Display (acf/post-display) - Custom post listings

Team & Forms

• Team Member (acf/team-member) - Team member profiles
• Email Form (acf/email-form) - Email capture forms
• Thread Builder (acf/thread-builder) - Discussion thread layouts

Block Structure

Each block follows a consistent directory structure:

blocks/
  block-name/
    ├── block.json          # Block metadata (required)
    ├── block-name.php      # Render template (required)
    ├── block-data.json     # ACF field group (auto-registered)
    ├── block-name.css      # Styles (conditionally loaded)
    └── extra.php           # Additional hooks (optional)

Key Features

Automatic Field Group Registration

Field groups are defined in JSON files (block-data.json or similar) within each block folder. These are automatically registered with ACF Pro when the plugin loads - no need to import/export through the ACF admin.

Native HTML Accordions

The Accordion block uses native HTML <details> and <summary> elements instead of JavaScript-based solutions. This provides:

• Zero JavaScript required
• Native keyboard accessibility
• Built-in browser support
• Reduced page weight

Conditional Asset Loading

CSS files are only enqueued when their respective blocks are used on a page, reducing unnecessary asset loading for better performance.

Optional Semantic Fallback Styles

Every rendered ACF block receives a shared .acf-block class and a zero-specificity 1.5rem block-end gap for baseline rhythm; normal theme and block margins take precedence. Settings → ACF Blocks License → Theme Compatibility Styles can optionally load a small semantic stylesheet for headings, paragraphs, lists, links, quotes, media, tables, code, forms, and native disclosure elements. Its selectors use :where() for zero specificity, so regular theme styles take precedence.

Creating Custom Blocks

1. Create a new directory in blocks/:

   mkdir blocks/my-block

2. Create block.json:

   {
     "apiVersion": 3,
     "name": "acf/my-block",
     "title": "My Block",
     "description": "Description here",
     "category": "common",
     "icon": "admin-post",
     "keywords": ["custom"],
     "acf": {
       "renderTemplate": "my-block.php",
       "blockVersion": 3
     },
     "supports": {
       "align": true,
       "mode": true,
       "jsx": true
     }
   }

3. Create block-data.json with your ACF field group configuration.

4. Create my-block.php render template.

5. Optionally add my-block.css for styles.

The block will be automatically registered on the next page load.

CSS Class Naming Convention

All blocks use the acf- prefix for CSS classes to avoid conflicts with other plugins and themes. For example:

• .acf-accordion - Accordion block container
• .acf-testimonial-block - Testimonial block container
• .acf-hero-block - Hero block container

This ensures styles are properly scoped and won't interfere with your theme's styling.

Development

Enable debug mode for detailed error logging:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

After changing block metadata, field JSON, or block CSS, regenerate the cached artifacts and run the full validation suite:

php tools/generate-manifest.php
php tools/build-editor-css.php
composer check

CI validates PHP 7.4, 8.1, 8.3, and 8.5, plus PHP/JSON/JavaScript syntax, generated artifacts, compatibility rules, and unit tests.

Support This Project

This free and open source plugin adds 23 ACF Pro blocks to the WordPress block editor, from FAQ accordions and product boxes to tabs and coupon codes. It registers each block's field group for you and I keep it maintained, with CI checks on PHP 7.4, 8.1, 8.3 and 8.5.

If the auto-registered field groups kept you out of the ACF admin's import and export tools, you can buy me a coffee.

A star on GitHub helps, and when a block breaks, an issue with the block name, your WordPress, PHP and ACF Pro versions and the steps that trigger it gives me enough to reproduce the problem.

License

GPL v2 or later

Credits

Built for Advanced Custom Fields Pro and WordPress block editor.