Support Log in
Field Forge Integrations

Field Forge + Gutenberg — Block Editor Integration

Field Forge field groups show as metaboxes in the block editor, 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.

Field Forge adds each field group as a metabox in the normal position with high priority, so the block editor shows it below the content area. The position is fixed in the code. Editors fill in field values the same way they would in the classic editor.

2. PHP-rendered Gutenberg blocks

You can register custom Gutenberg blocks with PHP render callbacks, where the render callback has full access to custom fields via get_field().

Field Forge defines acf_register_block_type(), the function name ACF Pro uses for such blocks. It takes one array of block settings and passes it to fieldforge_register_block_type() of the Pro add-on, so existing registrations work after migration while the Pro add-on is active.

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 →


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 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.


How values are loaded

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. Field Forge reads the top-level values of a post with one query and caches them with the WordPress object cache.


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?

See pricing →

The field group metabox in the block editor is in the free plugin; PHP blocks are a Pro feature.

Forge AI Assistant Online

Hi! I'm the Field Forge AI assistant. Ask me anything about the plugin — setup, features, troubleshooting, or development.

Just now
Powered by Forge AI · Browse docs