ACF Block Registration

Creating ACF PRO blocks with custom field groups for the Oh My Brand! FSE theme.

When to Use

• Creating blocks that use ACF field groups for content entry
• Building blocks with repeater fields, galleries, or complex field layouts
• Leveraging ACF PRO features (repeaters, flexible content, clone fields)
• Rapid block prototyping with ACF's visual field editor

ACF vs Native Blocks

Block File Structure

ACF blocks live in blocks/acf-{block-name}/:

blocks/acf-faq/
├── block.json          # ACF block metadata (ACF schema)
├── render.php          # Render template (referenced in block.json)
├── helpers.php         # Block-specific helper functions
├── style.css           # Frontend styles (auto-enqueued)
└── editor.css          # Editor-only styles (optional)

Field groups are stored separately in acf-json/.

File Templates

Use templates from block-scaffolds:

Full Examples

block.json Key Properties (ACF)

ACF Mode Options

Field Group Structure

Field groups connect to blocks via location rules:

"location": [
    [
        {
            "param": "block",
            "operator": "==",
            "value": "acf/faq"
        }
    ]
]

Title Conventions

Render Template Guidelines

Template Variables

Helper Function Guidelines

Common Field Types

Repeater Field

$items = get_field('repeater_field_name') ?: [];

foreach ($items as $item) {
    $sub_value = $item['sub_field_name'] ?? '';
}

Gallery Field

$images = get_field('gallery') ?: [];

foreach ($images as $image) {
    $url = $image['url'] ?? '';
    $alt = $image['alt'] ?? '';
}

Image Field

$image = get_field('image');

if ($image) {
    $url = $image['url'];
    $alt = $image['alt'];
}

Options Page Fields

$logo = get_field('site_logo', 'option');

Step-by-Step Creation

1. Create directory: mkdir -p blocks/acf-my-block
2. Add block.json: Copy from template, use ACF schema
3. Create field group: In WP Admin > ACF > Field Groups
   • Title: Block: {Block Name}
   • Location: Block equals acf/{block-name}
4. Create render.php: Copy from template
5. Create helpers.php: Copy from template
6. Add style.css: See css-standards
7. Register block: Add to $acf_blocks array in functions.php
8. Verify: Block appears in editor and renders correctly

Or use the scaffolding script:

.github/skills/block-scaffolds/scripts/create-block.sh acf my-block "My Block Title"

Related Skills

• block-scaffolds - Copy-paste templates
• php-standards - PHP conventions
• css-standards - CSS conventions
• phpunit-testing - Testing ACF blocks
• native-block-development - Native blocks

References

• ACF Block Registration
• ACF Block JSON Schema
• ACF Field Types
• ACF Local JSON