Building Custom Gutenberg Blocks with ACF

Native Gutenberg blocks are written in React, ship with a build step, and store their markup in post content. That is the right model for WordPress core, but for agency work it has a real cost: every design tweak to a block can mean deprecation handling and content migration. ACF Pro offers a different trade: blocks defined in PHP, rendered by a template, with fields providing the editing interface. For most client sites it is the pragmatic choice.

How ACF blocks work

An ACF block stores field data, not markup, in the post. When the editor loads, ACF renders your PHP template in a preview iframe; on the front end the same template runs again. Because the saved content is just structured data, you can change the markup at any time without invalidating existing posts. That single property removes the most painful part of block maintenance.

Registering a block the modern way

Since ACF 6, blocks are registered with block.json, the same metadata format core uses. We keep each block in its own directory inside the theme with its metadata, template, styles and field group export side by side.

{
  "name": "strcli/testimonial",
  "title": "Testimonial",
  "category": "theme",
  "icon": "format-quote",
  "supports": { "align": false, "anchor": true },
  "acf": {
    "mode": "preview",
    "renderTemplate": "render.php"
  }
}

Registration is one call per block directory from your theme setup file, using register_block_type with the path to the folder containing block.json. The render template receives the block array and can read fields with get_field as usual. Keep templates dumb: read fields at the top, escape everything on output, and push any real logic into a class or helper the template calls.

A typical template reads its fields first, bails early when required content is missing, and builds its class list from the block's settings so anchor and alignment support keep working. Because it is plain PHP, everything the theme already offers, partials, helpers, escaping functions, is available without ceremony, which is exactly why front-end and back-end developers can both work on blocks without a JavaScript build sitting between them.

Fields as code

Field groups defined by clicking around the admin do not belong in version control by default, and that is a problem the moment a second developer joins. Use ACF JSON so every field group saves to the theme automatically, and review field changes in pull requests like any other code. It also means deployments carry field changes with them, with no manual syncing between environments. We point the ACF JSON save path into each block's own directory, so deleting a block folder removes everything the block owned.

Patterns that keep block libraries sane

• Name blocks by content, not appearance: a testimonial block, not a grey-box-with-quote block.
• Give every block an empty state so the preview never renders as a blank void when fields are unfilled.
• Set example data in block.json so the block preview in the inserter shows something real.
• Restrict which blocks are available per post type; forty blocks in the inserter helps nobody.
• Compose with InnerBlocks where editors need freedom inside a section, rather than adding a field for every possibility.

Where ACF blocks stop being the answer

The editing experience is a preview, not true inline editing: editors fill in fields in the sidebar and watch the preview update. For most marketing sites that is perfectly acceptable, and editors often prefer it to fiddly on-canvas controls. But if you need rich inline editing, drag-to-reorder child elements, or blocks destined for distribution beyond one site, native blocks built with the core tooling are the better investment. The two approaches coexist happily in one theme, so use each where it is strongest.

A well-organised ACF block library is the fastest route we know to a WordPress editing experience clients actually enjoy using, and it stays maintainable for years.

Need a block library built properly? STRCLI designs and builds Gutenberg editing experiences for agencies and in-house teams alike.