Advanced Custom Fields (ACF) is a powerful plugin for WordPress that allows you to create custom fields for your posts, pages, and custom post types. With this tutorial, you’ll learn how to create a custom Gutenberg block that displays an ACF field on the front-end of your website.
We will cover, step by step
- Step 1: Create a new plugin
- Step 2: Define the Block
- Step 3: Create the block.json file
- Step 4: Create the Javascript Source Files
- Step 5: Building the source files
- Step 6: Package and install the plugin
Step 1: Create a new plugin
The first step to creating your server-side rendered ACF field block is to create a new plugin for your block. Simplest way to do this this is by creating a new directory and adding a plugin file, typically named plugin.php, to the directory. For example ‘ACFBlock/plugin.php’ and adding this comment at the top to define it:
<?php
/**
* Plugin Name: ACF Block
* Description: Display an ACF field on your WordPress site.
* Version: 1.0
* Author: Your Name
* Author URI: http://example.com
*/
Step 2: Define the Block
In the same main plugin file, you’ll need to use the register_block_type function to define your block. This function accepts an array of properties that define the behavior and appearance of the block. In this case, we’ll set the render_callback property to a function that will be responsible for displaying the ACF field on the front-end of the site.
Here’s an example of what your code might look like:
function wpblockz_acf_field_render($attributes, $content, $block) {
if (!function_exists('get_field')) { return ''; }
$key = sanitize_text_field($attributes['fieldKey'] ?? '');
$post_id = $block->context['postId'] ?? get_the_ID();
if (!$key || !$post_id) { return ''; }
$value = get_field($key, $post_id);
if (!is_scalar($value)) { return ''; }
return '<div class="acf-block">' . esc_html((string) $value) . '</div>';
}
add_action('init', function () {
register_block_type(__DIR__ . '/build', [
'render_callback' => 'wpblockz_acf_field_render',
]);
});
In this example, the my_acf_block_render function is responsible for displaying the ACF field. The $field_key variable is passed in as an attribute when the block is inserted into the post or page. The get_field function is used to retrieve the value of the ACF field with the given key. The my_acf_block_init function is used to register the block with WordPress, and the add_action function is used to run the my_acf_block_init function when the init action is triggered.
Step 3: Create the block.json file
The block.json file is used to define the configuration and metadata of your block, such as the name, description, and category of the block. This file should be created in your plugin folder.
Here’s an example of what your block.json file might look like:
{
"apiVersion": 3,
"name": "wpblockz/acf-field",
"title": "ACF Field",
"category": "widgets",
"icon": "admin-tools",
"attributes": {
"fieldKey": {
"type": "string",
"default": ""
}
},
"usesContext": [
"postId"
],
"editorScript": "file:./index.js"
}
Use the same lowercase block name on the server and client: wpblockz/acf-field. Keep the source metadata in src/block.json; the standard build copies it to the build directory.
The fieldKey attribute stores the ACF field name or key. Register the PHP callback through register_block_type(); render_callback is not a JSON metadata field.
Step 4: Create the Javascript Source File
Create src/index.js for the client registration and editing interface.
- Create a new folder called
srcin the plugin folder. - Within the
srcfolder, create a new file calledindex.jsand paste in the following code:
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';
import metadata from './block.json';
registerBlockType(metadata.name, {
...metadata,
edit: ({ attributes, setAttributes }) => (
<div {...useBlockProps()}>
<InspectorControls>
<PanelBody title="ACF field">
<TextControl label="Field name or key"
value={attributes.fieldKey}
onChange={(fieldKey) => setAttributes({ fieldKey })} />
</PanelBody>
</InspectorControls>
<p>ACF field: {attributes.fieldKey || 'Choose a field in the sidebar'}</p>
</div>
),
save: () => null,
});
The edit function uses a TextControl to store the ACF field name. It does not call an unsupported getField method from the core data store.
The control sets the block attribute. The placeholder explains which field will be read; the actual value is rendered by PHP.
The save function returns null because this is a dynamic block. WordPress stores the attributes and calls the PHP render callback for the current post.
Step 5: Building the source files
To make sure your code runs smoothly, you’ll need to compile it using build tools. In this tutorial, we’ll be using wp-scripts, which is a package included in the WordPress development environment. To add wp-scripts to your project, follow these steps:
npm install --save-dev @wordpress/scripts
- Create a new file called
wp-scripts.config.jsin your project root. - Add the following code to the file to configure your build:
{
"name": "wpblockz-acf-field",
"private": true,
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
}
}
Run the following command to build your code:
npx wp-scripts build
This builds src/index.js and copies src/block.json into build/. Include the generated index.asset.php and built files in the plugin ZIP.
The entire file structure of your plugin should look like this:
acf-block/
├── plugin.php
├── package.json
├── src/
│ ├── block.json
│ └── index.js
└── build/
├── block.json
├── index.js
└── index.asset.php
Step 6: Package and install the plugin
To package your plugin, you’ll need to compress the entire plugin folder into a .zip file. This file can be uploaded to your WordPress site using the Plugins > Add New > Upload Plugin screen. Once the plugin is installed and activated, you’ll be able to add the ACF Block to your posts and pages, and enter the key for the ACF field that you want to display.
And that’s it! You now have a basic understanding of how to create a server-side rendered ACF field block for WordPress. I hope this tutorial has been helpful and that you have fun building your own custom blocks. Good luck!
Field types and prerequisites
Activate ACF and create a field group with a text or other scalar field assigned to the target post type. This example uses ACF’s get_field() API, not the ACF PRO block-registration API. Array-valued fields such as galleries and repeaters need their own rendering logic. Escape output for its context; this text-only example uses esc_html().



