Gutenberg Custom Fields — Field Forge Block Editor Integration

Field Forge integrates natively with WordPress’s Gutenberg block editor. Field groups render as metaboxes in the block editor sidebar or below the content area. Custom Gutenberg blocks can register with PHP render callbacks that access Field Forge values via get_field() — either via the fieldforge_register_block_type() function or the ACF-compatible acf_register_block_type().

Two ways to use Field Forge with Gutenberg

1. Field groups as metaboxes

This is the standard WordPress custom fields approach. Create a field group in Field Forge’s visual builder, assign it via location rules to a post type, and it appears as a metabox when editing posts of that type.

In Gutenberg, metaboxes can be:

Below the content area — position=”normal” — below the block editor
In the sidebar — position=”side” — in the document sidebar
In the advanced section — position=”advanced” — collapsed below the main editor

All three positions work natively with Gutenberg. Editors fill in field values the same way they would in the classic editor.

2. PHP-rendered Gutenberg blocks

This is where Field Forge gets more interesting for developers. You can register custom Gutenberg blocks with PHP render callbacks, where the render callback has full access to custom fields via get_field().

This is the same approach ACF Pro popularized with acf_register_block_type() — and Field Forge supports the exact same function signature for migration compatibility.

add_action('init', function() {
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type([
            'name'            => 'hero-section',
            'title'           => 'Hero Section',
            'description'     => 'A hero section with title, subtitle, and CTA.',
            'render_callback' => 'render_hero_section_block',
            'category'        => 'theme',
            'icon'            => 'cover-image',
            'keywords'        => ['hero', 'section'],
            'supports'        => [
                'align' => ['wide', 'full'],
                'anchor' => true,
            ],
        ]);
    }
});

function render_hero_section_block($block) {
    $title = get_field('title');
    $subtitle = get_field('subtitle');
    $background_image = get_field('background_image');
    ?>
    <section class="hero">
        <?php if ($background_image) : ?>
            <img src="<?php echo esc_url($background_image['url']); ?>" alt="">
        <?php endif; ?>
        <h1><?php echo esc_html($title); ?></h1>
        <p><?php echo esc_html($subtitle); ?></p>
    </section>
    <?php
}

Assign a field group to this block via location rules:

Location Rules:
  Block is equal to "acf/hero-section"

When an editor adds this block to a Gutenberg post, the field group renders inside the block’s inspector panel. Editors fill in the fields, the block re-renders with live preview, and the frontend output comes from the PHP callback.

Full PHP blocks feature →

Auto-detection of FAQ blocks

Field Forge auto-detects FAQ-style content built with Gutenberg’s Accordion or Details blocks. When a post uses these blocks, Field Forge exposes them as structured data for FAQ schema generation (this is the cross-plugin integration with SEO Forge).

You don’t need to manually register FAQ fields — Field Forge reads the block structure and makes the data available programmatically.

Block pattern integration

Field Forge field groups can be used inside block patterns. Save a reusable pattern that includes a Field Forge-powered custom block, and editors can drop the pattern into any post to instantly get a pre-configured block with custom fields attached.

Full Site Editing (FSE) compatibility

For sites using WordPress’s Full Site Editing mode (block themes with site editor), Field Forge works normally:

Field groups render in block theme post editors
Custom Gutenberg blocks registered via acf_register_block_type() work in the site editor
Template parts can include Field Forge-powered blocks
Global styles integrate with Field Forge blocks via the supports configuration

Dynamic blocks with InnerBlocks

For more complex block patterns, combine Field Forge blocks with Gutenberg’s <InnerBlocks /> component:

acf_register_block_type([
    'name' => 'two-column-with-fields',
    'render_callback' => 'render_two_column_block',
    'supports' => [
        'inner_blocks' => true,
    ],
]);

function render_two_column_block($block) {
    $sidebar_title = get_field('sidebar_title');
    $sidebar_content = get_field('sidebar_content');
    ?>
    <div class="two-column">
        <aside class="sidebar">
            <h3><?php echo esc_html($sidebar_title); ?></h3>
            <div><?php echo wp_kses_post($sidebar_content); ?></div>
        </aside>
        <main>
            <InnerBlocks />
        </main>
    </div>
    <?php
}

The sidebar area is powered by custom fields, the main area is standard Gutenberg blocks. Users get the best of both worlds.

Performance

Field Forge’s field values are loaded via the object cache on the first block render, and subsequent renders on the same page are cache hits. For pages with multiple custom blocks, this means one database query per unique field, regardless of how many blocks use it.

Combined with custom table storage, Gutenberg pages with many Field Forge-powered blocks load faster than equivalent ACF-powered pages.

Migrating from ACF block registrations

If you have existing acf_register_block_type() calls in your theme, they keep working unchanged after migrating from ACF to Field Forge. The compat layer implements acf_register_block_type() with the same signature, routing to Field Forge’s block registration internally.

No code changes needed. Your Gutenberg blocks continue to render via PHP callbacks that use get_field() — which now resolves to Field Forge’s storage instead of ACF’s.

Ready to use Field Forge in the block editor?

Get Field Forge — from $35/year →

Gutenberg integration is included in every version of Field Forge, including the free one.

Field Forge + Gutenberg — Block Editor Integration