Skip to content

Migrating from ACF Blocks

If you have been building custom WordPress blocks with ACF (Advanced Custom Fields), migrating to Blockstudio is straightforward. The concepts are similar: you define fields, write a template, and the block appears in the editor. The differences are that Blockstudio discovers block folders on its own, declares fields in its own schema inside block.json, and hands every template its field values as one $a array.

This guide walks through the migration step by step, with side-by-side comparisons of ACF and Blockstudio patterns.

The core difference

Since ACF 6.0, an ACF block is a block.json with an acf key that names its render template, and every block folder is registered with its own register_block_type() call. The fields come from a field group attached to the block with a Block location rule (built in the admin, synced through Local JSON, or registered with acf_add_local_field_group()), or, since ACF PRO 6.8.1, from an inline acf.fields array in the same block.json. Blockstudio replaces the registration call with file-based auto-discovery: create a folder with a block.json and an index.php, and the block is registered automatically.

ACF:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
acf_add_local_field_group([
  'key'      => 'group_hero',
  'title'    => 'Hero Fields',
  'fields'   => [
    ['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
    ['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
  ],
  'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
PHP
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($title); ?></h1>
</div>

Blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($a['title']); ?></h1>
</div>

No registration call and no render callback: the folder structure is the registration, and the fields live in block.json next to the template. The template reads $a instead of calling get_field().

Block registration

ACF

Current ACF blocks are registered from a block.json with an acf key (renderTemplate or renderCallback, plus options such as blockVersion), loaded by an explicit register_block_type() call per block folder, typically on init in functions.php or a plugin file. Older blocks may still use acf_register_block_type(), which ACF has documented as deprecated since ACF 6.0; it keeps working, so migrate those blocks the same way.

Blockstudio

Create a folder in your theme’s blockstudio/ directory (or blocks/ if you prefer). Add a block.json with the standard WordPress block metadata plus a blockstudio key. That is it.

Code
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

The block.json uses the standard WordPress block.json format with the blockstudio key for fields and configuration:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

Accessing field values

This is the most common change you will make during migration.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (always available)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

The $a variable is a shorthand for $attributes and contains all field values for the current block. It is always available in the template, both in the editor and on the frontend.

Template variables

Blockstudio provides several variables in every template:

Variable Shorthand Description
$attributes $a All field values
$block $b Block metadata (name, title, dir, url, postId)
$context $c Parent block context
$content InnerBlocks content
$post_id Current post ID (works in editor and frontend; post_id or postId in Twig)

Field type mapping

Most ACF field types have a direct equivalent in Blockstudio. The JSON syntax is different, but the concepts map cleanly.

Text and content fields

ACF:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }

For editable text in the block editor (not just a text input), use the richtext type with the <RichText /> component:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Image and file fields

ACF’s image and file fields map to Blockstudio’s files type:

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }

The returned object structure is similar:

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

Available properties: ID, title, alt, caption, description, href, url, sizes. The dimensions are in sizes, for example $a['photo']['sizes']['full-width'].

Select, radio, and checkbox

ACF:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "id": "color",
  "type": "select",
  "label": "Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

Use "returnFormat": "both" to get both value and label:

PHP
echo $a['color']['value'];  // "red"
echo $a['color']['label'];  // "Red"

The same pattern applies to radio and checkbox types.

Toggle and true/false

ACF:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

Color and gradient

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

The color type integrates with the WordPress color palette. The gradient type provides a gradient picker.

Number, range, and date

ACF:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }

Repeaters

ACF’s repeater field maps directly to Blockstudio’s repeater type. ACF templates usually loop with have_rows() / the_row() / get_sub_field() (get_field() on a repeater also returns an array of rows); Blockstudio only has the plain PHP array, already in $a.

ACF:

PHP
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
  ['name' => 'title', 'type' => 'text'],
  ['name' => 'description', 'type' => 'textarea'],
]]

// Template
if (have_rows('features')) :
  while (have_rows('features')) : the_row();
    echo get_sub_field('title');
    echo get_sub_field('description');
  endwhile;
endif;

Blockstudio:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?php foreach ($a['features'] as $feature) : ?>
  <h3><?php echo esc_html($feature['title']); ?></h3>
  <p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>

Blockstudio repeaters support nesting (repeater inside repeater) up to 3 levels.

Groups

ACF’s group field maps to Blockstudio’s group type. Field IDs inside groups are prefixed with the group ID.

ACF:

PHP
['name' => 'author', 'type' => 'group', 'sub_fields' => [
  ['name' => 'name', 'type' => 'text'],
  ['name' => 'role', 'type' => 'text'],
]]

// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];

Blockstudio:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>

The bs_get_group() helper strips the group prefix from field IDs, giving you clean access. Without it, you would access fields as $a['author_name'] and $a['author_role'].

Conditional logic

Both ACF and Blockstudio support conditional logic for showing and hiding fields based on other field values.

ACF:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}

Blockstudio conditions reference field IDs directly (not field keys). Available operators: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio also supports global conditions based on post type, post ID, user role, and user ID:

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

Both ACF and Blockstudio support InnerBlocks for nesting other blocks inside your custom block, with the same <InnerBlocks /> tag and the same allowedBlocks, template and templateLock attributes, so this part of a template usually carries over unchanged.

Blockstudio:

PHP
<div useBlockProps class="my-wrapper">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
    template='<?php echo esc_attr(wp_json_encode([
      ["core/heading", ["placeholder" => "Section title"]],
      ["core/paragraph", ["placeholder" => "Section content"]]
    ])); ?>'
    templateLock="insert"
  />
</div>

The <InnerBlocks /> tag is replaced with the React component in the editor and with the rendered block content on the frontend.

Post meta storage

Both ACF Blocks and Blockstudio store field values as block attributes in the post content by default, not in post meta. This means field values are not queryable with WP_Query unless you opt in to meta storage.

ACF added opt-in post meta storage for blocks in ACF PRO 6.3 via usePostMeta: true, for one top-level block per page. Blockstudio has an opt-in mechanism per field, using the storage property:

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
}

The meta key is auto-registered with show_in_rest. Access it anywhere with get_post_meta($post_id, 'is_featured', true).

For site-wide values (like ACF options pages), use option storage:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Extending existing blocks

ACF’s Block location rule attaches field groups to ACF blocks only; it does not add fields to core or third-party blocks. ACF’s route to core blocks such as Heading, Paragraph, Image and Button is the WordPress Block Bindings API, which connects existing block attributes to ACF field values. Blockstudio can add new fields and controls to any registered block through extension files.

Create an extension file in your blockstudio directory:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

The set property automatically applies the field value to the block’s HTML. Use wildcards to extend multiple blocks at once: "name": "core/*".

Migration checklist

  1. Create the block folder in theme/blockstudio/{block-name}/ with block.json and index.php.
  2. Move field definitions from the block’s field group (Local JSON, acf_add_local_field_group(), or an inline acf.fields array) to the blockstudio.attributes array in block.json. Change name to id, remove key, and adjust type names as needed.
  3. Update template access from get_field('name') to $a['name']. Replace have_rows() loops with foreach ($a['repeater'] as $item).
  4. Replace get_sub_field() with direct array access: $item['fieldId'].
  5. Add useBlockProps to the outermost element in your template for proper editor integration.
  6. Move conditional logic from ACF’s conditional_logic to Blockstudio’s conditions, referencing field IDs instead of field keys.
  7. Add storage for any fields that were previously queried via get_post_meta() or used in WP_Query.
  8. Remove ACF registration code: the register_block_type() calls and acf keys of the migrated blocks (or their acf_register_block_type() calls), and their field groups, whether they live in Local JSON, acf_add_local_field_group(), an inline acf.fields array, or the admin.
  9. Test in the editor to verify fields appear correctly, then check the frontend output.