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:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
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
$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:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<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.
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:
{
"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:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "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:
{ "id": "heading", "type": "richtext" }
<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:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "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:
// 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:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
Use "returnFormat": "both" to get both value and label:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
The same pattern applies to radio and checkbox types.
Toggle and true/false
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Link field
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Color and gradient
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "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:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "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:
['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:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?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:
['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:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?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:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "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:
{
"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:
<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:
{
"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:
{
"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:
{
"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
- Create the block folder in
theme/blockstudio/{block-name}/withblock.jsonandindex.php. - Move field definitions from the block’s field group (Local JSON,
acf_add_local_field_group(), or an inlineacf.fieldsarray) to theblockstudio.attributesarray inblock.json. Changenametoid, removekey, and adjust type names as needed. - Update template access from
get_field('name')to$a['name']. Replacehave_rows()loops withforeach ($a['repeater'] as $item). - Replace
get_sub_field()with direct array access:$item['fieldId']. - Add
useBlockPropsto the outermost element in your template for proper editor integration. - Move conditional logic from ACF’s
conditional_logicto Blockstudio’sconditions, referencing field IDs instead of field keys. - Add storage for any fields that were previously queried via
get_post_meta()or used inWP_Query. - Remove ACF registration code: the
register_block_type()calls andacfkeys of the migrated blocks (or theiracf_register_block_type()calls), and their field groups, whether they live in Local JSON,acf_add_local_field_group(), an inlineacf.fieldsarray, or the admin. - Test in the editor to verify fields appear correctly, then check the frontend output.