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
• Optional Dark Mode: Choose whether blocks use dark fallback colors when a visitor's device prefers dark
• 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

Marketing

• Pricing (acf/pricing) - Plan cards with a highlighted tier and feature lists
• Logo Cloud (acf/logo-cloud) - Customer or press logos
• Steps (acf/steps) - Numbered “how it works” sequence
• Trust Bar (acf/trust-bar) - Short guarantees under an offer

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.

Optional Dark Mode

Settings → ACF Blocks License → Dark Mode controls assets/css/tokens-dark.css, which swaps the fallback color of any token the active theme does not define when the visitor's device prefers dark. It is off by default. Turn it on only if the site itself goes dark with the device, because these colors can make text unreadable on a light page. Colors the theme defines keep following the theme either way, including its own dark mode toggle. Code can force the choice with the acf_blocks_dark_mode_enabled filter.

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
node --test tests/*.test.js
php tools/check-release.php
composer audit --locked

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

Release tags must match the plugin header, ACF_BLOCKS_VERSION, and changelog. The script cache version in blocks/video-block/youtube-preview.html must match too. The tag workflow runs the checks before packaging; development dependencies and tests stay out of the upload ZIP.

AJAX loaders that introduce the first Video block must also enqueue its registered styles and view script. Once the script is present, newly added Video blocks are initialized automatically.

Use explicit keyword values for boolean HTML attributes in ACF previews, such as hidden="hidden" and controls="controls". ACF's React preview can drop empty attribute values; WordPress helpers such as checked() already emit the explicit form.

Webhook forms send an opaque signed reference to the site. The server resolves the current saved form settings and sends its credentials directly to the configured HTTPS service, without following redirects. Forms in published posts, reusable blocks, active templates/template parts, and active block widgets are supported. Unsaved previews cannot submit webhooks. After updating from a version that exposed webhook authentication headers, purge cached form pages and rotate those credentials with the webhook provider.

Star Rating uses the connecting IP by default. Only enable the existing acf_star_rating_trust_cloudflare_header filter when the origin is restricted to trusted Cloudflare traffic; a request header alone cannot establish trust.

The optional tests/storage-wordpress-integration.php, tests/migration-concurrency-integration.php, and tests/render-wordpress-integration.php runners exercise a disposable WordPress/MariaDB database, including separate concurrent PHP processes. Set ACFB_TEST_WP_ROOT to readable WordPress core, ACFB_TEST_SANDBOX to a temporary directory, and ACFB_TEST_MYSQL_SOCKET to an isolated MariaDB socket. Rendering checks also need ACFB_TEST_ACF_PLUGIN, pointing to an ACF Pro or SCF acf.php. These runners must use a dedicated test database, never an existing site's database. tests/toc-gallery-browser.js optionally runs the real-template browser checks when Playwright and Chrome are available. tests/theme-visual-browser.js checks theme palette precedence, operating-system fallbacks, and URL Preview button contrast and sizing in an offline browser. tests/queue-transaction-integration.php covers queue visibility across commit and rollback using the same isolated database settings.

Privacy

No telemetry: ACF Blocks doesn't send usage statistics, your content or your visitors' data to gauravtiwari.org.

when you activate a license, ACF Blocks sends the license key, the product ID, your site address and the plugin version to the FluentCart store at gauravtiwari.org. It contacts the store again when you deactivate the license and when WordPress checks for updates. Nothing is sent before you enter a key. Update packages download over HTTPS from the store or its Cloudflare R2 storage.

Blocks that make outside requests:

• Video block: YouTube thumbnails load from i.ytimg.com with the page. The YouTube or Vimeo player loads only after the visitor clicks, from youtube.com or player.vimeo.com.
• Email form block: submissions go to the HTTPS webhook you configure.
• URL preview block and the image localizer fetch only URLs and images an editor adds to content.

Data stored on your site:

• Star ratings keep a daily hash of the voter's IP address on the server and a flag in the visitor's browser storage so a vote counts once.
• The checklist block saves its state in the visitor's browser storage.

The store's privacy policy covers license data.

Support This Project

This free and open source plugin adds 33 ACF Pro blocks to the WordPress block editor, from FAQ accordions and product boxes to pricing tables, logo clouds, 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.