Using ACF Blocks for Gutenberg

Introduction

Gutenberg has transformed the WordPress editing experience by introducing a block-based approach. While core blocks cover most needs, Advanced Custom Fields (ACF) Pro empowers developers to create tailor-made blocks quickly. This article explores using ACF Blocks for Gutenberg, offering best practices, code examples, and performance considerations.

Why Choose ACF Blocks

• Low Overhead: Leverages ACF’s familiar API without deep React knowledge.
• Rapid Development: Field groups and blocks defined in PHP or JSON.
• Flexibility: Supports complex layouts, repeaters, and conditional logic.
• Seamless Integration: Data saved as post meta and accessible via template functions.

Prerequisites

1. WordPress 5.0 or higher with Gutenberg enabled.
2. ACF Pro (blocks are a pro feature).
3. Basic PHP development environment and theme or plugin to register blocks.

Registering an ACF Block

Use acf_register_block_type in your theme’s functions.php or plugin file:

add_action(acf/init, function(){
    acf_register_block_type(array(
      name              =gt hero,
      title             =gt __(Hero Section,text-domain),
      description       =gt __(A custom hero block.,text-domain),
      render_callback   =gt render_hero_block,
      category          =gt layout,
      icon              =gt cover-image,
      keywords          =gt array(hero,banner),
      mode              =gt preview,
      supports          =gt array(align=gtfalse)
    ))
})

Key Arguments Explained

• name: Unique slug for the block (lowercase, hyphens).
• title: Human-readable block name.
• render_callback: Function that outputs HTML.
• category: Block group in the inserter (e.g., layout).
• mode: Default editing mode (edit or preview).

Defining Block Fields

Fields are assigned via acf_add_local_field_group:

acf_add_local_field_group(array(
  key      =gt group_hero,
  title    =gt Hero Fields,
  fields   =gt array(
    array(
      key   =gt field_hero_image,
      label =gt Background Image,
      name  =gt hero_image,
      type  =gt image
    ),
    array(
      key   =gt field_hero_heading,
      label =gt Heading,
      name  =gt hero_heading,
      type  =gt text
    ),
    array(
      key   =gt field_hero_cta,
      label =gt CTA Button,
      name  =gt hero_cta,
      type  =gt link
    )
  ),
  location =gt array(array(
    array(
      param    =gt block,
      operator =gt ==,
      value    =gt acf/hero
    )
  ))
))

Rendering the Block

The render_hero_block callback handles front-end output:

function render_hero_block(block, content = , is_preview = false){
  heading =gt get_field(hero_heading)
  image   =gt get_field(hero_image)
  cta     =gt get_field(hero_cta)

  echo ltsection class=hero-block style=background-image:url(.esc_url(image[url]).) padding:60px color:#fffgt
  if(heading) echo lth2gt.esc_html(heading).lt/h2gt
  if(cta)    echo lta href=.esc_url(cta[url]). style=background:#0066cc color:#fff padding:10px 20px text-decoration:noneborder-radius:4pxgt.esc_html(cta[title]).lt/agt
  echo lt/sectiongt
}

Block Styles and Scripts

To enqueue custom styles or scripts for both editor and front-end:

function hero_block_assets(){
  wp_enqueue_style(hero-block-style, get_theme_file_uri(/css/hero.css))
  if(is_admin()){
    wp_enqueue_script(hero-block-editor, get_theme_file_uri(/js/hero-editor.js), array(wp-blocks,wp-element), null, true)
  }
}
add_action(enqueue_block_assets,hero_block_assets)

ACF JSON vs PHP

Storing field groups in JSON supports version control and portability. Enable by creating acf-json in your theme root. PHP registration is fine for dynamic or environment-based configurations.

Comparison: ACF Blocks vs Native Block

Feature	ACF Block	Native Block
Development Language	PHP	React/JSX
Learning Curve	Low	Moderate to High
Data Storage	Post Meta	Block Attributes

Best Practices

• Prefix block names and field keys to avoid collisions.
• Sanitize all output using esc_html, esc_url, etc.
• Leverage supports to limit options (alignments, HTML, etc.).
• Use server-side rendering (render_callback) for dynamic content.

Troubleshooting

• Block Not Appearing: Confirm ACF Pro is active and acf/init hook fires.
• Fields Missing: Check location matches your block slug.
• No Styles Applied: Ensure enqueue_block_assets is hooked correctly.

Further Resources

• ACF Register Block Type
• ACF Block Attributes
• WordPress Block Editor Handbook

Conclusion

ACF Blocks streamline Gutenberg development for PHP-savvy teams, reducing reliance on React. By following structured registration, field definition, and rendering patterns, you can build rich, maintainable custom blocks. Leverage JSON for portability, sanitize outputs diligently, and keep performance in mind for an optimal author and end-user experience.