ACF Complete Guide: Field Types, Options Pages, ACF Blocks, REST API

This article is a localized edition of the Japanese original. Read the Japanese original

ACF (Advanced Custom Fields) is a data-modeling tool for WordPress that goes well beyond adding input fields to posts: it also handles site-wide settings pages, custom blocks, file-based field definitions, and exposing values through the REST API. This article walks through the field types, the differences between the free version and PRO, options pages, ACF Blocks, Local JSON and the REST API, and also sorts out how ACF and Secure Custom Fields (SCF) have related since 2024. By the end you'll be able to decide, project by project, "which features to use and where to store the data."

The very first steps, such as creating a field group and displaying values with get_field(), are covered in "ACF Basics," so if you're new to ACF it will be easier to start there.

How ACF and Secure Custom Fields relate

ACF is currently developed by WP Engine. In September 2024 the dispute between WordPress.org and WP Engine came into the open, and on October 12, 2024, WordPress.org released "Secure Custom Fields (SCF)," a fork of ACF, and replaced ACF's listing in the plugin directory with SCF. During this period WP Engine distributed ACF from its own website and set up its own update channel.

Then in December 2024, following a preliminary injunction granted by a court at WP Engine's request, the ACF listing in the directory and control over it were returned to WP Engine. SCF continues to be listed as a separate plugin (slug secure-custom-fields) and has also absorbed PRO-equivalent features. Because the two use the same function names, do not activate them at the same time. The lawsuit is reported to be continuing toward a judgment on the merits, and each plugin's direction may still change (as of October 2026).

What matters operationally is knowing which of the two your site runs and where it gets updates from. Check the name and author in the plugin list, and if you switch, verify the display and data on a staging environment before applying it to production.

Free version vs. ACF PRO

This is a case where a comparison helps, so here is a table.

Prices and licensing can change, so check the official website before you buy. As a rule of thumb, PRO becomes a candidate if you need any of the following: "data whose number of rows varies (price tables, FAQs, etc.)," "settings used across the whole site," or "custom blocks."

Overview of field types

In the admin screen you choose field types by category. The main ones are:

• Basic: Text, Text Area, Number, Range, Email, URL, Password
• Content: Image, File, WYSIWYG Editor, oEmbed, Gallery (PRO)
• Choice: Select, Checkbox, Radio Button, Button Group, True / False
• Relational: Link, Post Object, Page Link, Relationship, Taxonomy, User
• Advanced: Google Map, Date Picker, Date Time Picker, Time Picker, Color Picker
• Layout: Message, Accordion, Tab, Group, Repeater (PRO), Flexible Content (PRO), Clone (PRO)

The key question when choosing is "will you use this later for searching or sorting?" If you'll sort posts by a date or a number, choose a Date Picker or Number field rather than Text and keep the storage format consistent; then comparisons in meta_query are straightforward to write. For Relationship and Post Object fields, setting the return value to "Post ID" lets you fetch only the information you need, and you won't have to puzzle over setup_postdata() inside the loop.

Options pages (PRO)

Values that belong to the whole site rather than to a post, such as the company phone number or a notice in the footer, go on an options page. In PRO you can create options pages from the admin screen, and you can also register them in code.

add_action( 'acf/init', function () {
	if ( ! function_exists( 'acf_add_options_page' ) ) {
		return;
	}
	acf_add_options_page( array(
		'page_title' => 'Site Settings',
		'menu_title' => 'Site Settings',
		'menu_slug'  => 'site-settings',
		'capability' => 'manage_options',
		'redirect'   => false,
	) );
} );

In the field group's location rules, set "Options Page" is equal to this page and the input fields will appear. To retrieve a value, pass 'option' as the second argument.

$tel = get_field( 'company_tel', 'option' );
if ( $tel ) {
	echo '<p class="footer-tel">' . esc_html( $tel ) . '</p>';
}

Values are stored in the wp_options table with keys starting with options_. capability decides who can edit the page, so decide first whether editors should be able to touch it or only administrators, then set it.

ACF Blocks (PRO)

With ACF Blocks you can build custom blocks using only PHP templates, without writing React. A block is defined by adding an acf key to WordPress's standard block.json.

{
	"name": "acf/testimonial",
	"title": "Testimonial",
	"category": "formatting",
	"icon": "format-quote",
	"apiVersion": 2,
	"acf": {
		"mode": "preview",
		"renderTemplate": "render.php"
	},
	"supports": {
		"align": false
	}
}

// functions.php: place block.json and render.php in the theme's blocks/testimonial/
add_action( 'init', function () {
	register_block_type( get_theme_file_path( 'blocks/testimonial' ) );
} );

<?php
// blocks/testimonial/render.php
$quote  = get_field( 'quote' );
$author = get_field( 'author_name' );

$class = 'testimonial';
if ( ! empty( $block['className'] ) ) {
	$class .= ' ' . $block['className'];
}

if ( ! $quote ) {
	if ( $is_preview ) {
		echo '<p>' . esc_html__( 'Please enter a testimonial.', 'your-textdomain' ) . '</p>';
	}
	return;
}
?>
<figure class="<?php echo esc_attr( $class ); ?>">
	<blockquote><?php echo esc_html( $quote ); ?></blockquote>
	<?php if ( $author ) : ?>
		<figcaption><?php echo esc_html( $author ); ?></figcaption>
	<?php endif; ?>
</figure>

If you set the field group's location rule to "Block" is equal to "Testimonial," the input fields appear in the block's settings panel. Inside the template you can use $block (the block settings) and $is_preview (whether it is being shown in the editor).

One caveat: ACF Block values are saved not as post meta but as block attributes inside the post body (post_content). That makes them unsuitable for searching with meta_query or sorting on archive pages. Splitting the roles, so that values used for searching and aggregation are stored as post meta through a regular field group, keeps your design from falling apart.

Managing field definitions with Local JSON

Field group definitions are normally stored in the database, but if you create an acf-json folder directly in your theme, the definition is written out as a JSON file every time you save. Manage these files with Git, and moving fields built in development to production becomes a matter of "deploying the files and syncing." When a file is newer, the field group list shows a prompt to sync, so review the contents and sync.

If you might switch themes, or want to keep field definitions in a functionality plugin, change the save and load locations with filters.

// Example of using an acf-json folder inside your own functionality plugin
add_filter( 'acf/settings/save_json', function ( $path ) {
	return plugin_dir_path( __FILE__ ) . 'acf-json';
} );

add_filter( 'acf/settings/load_json', function ( $paths ) {
	$paths[] = plugin_dir_path( __FILE__ ) . 'acf-json';
	return $paths;
} );

If you edit fields directly in the admin screen on production, the JSON and the database drift apart. Agreeing on a team rule such as "change definitions in development, deploy the JSON and sync" prevents accidents. Note that Local JSON also covers definitions for post types, taxonomies and options pages.

Exposing values through the REST API

If you enable "Show in REST API" in the field group settings, an acf key is added to responses from standard endpoints such as /wp-json/wp/v2/posts/123, containing the field values. For a custom post type, the post type itself must have show_in_rest enabled.

Keep in mind that anyone can fetch the REST response for a published post. Do not enable REST API display for groups that include fields holding internal notes or personal information. If a request is authenticated and the user has edit permissions, acf values can also be written through an update request to the same endpoint. Options page values aren't included in the standard post endpoints, so if you need them externally, create your own endpoint with register_rest_route(), add a permission check, and return them from there.

Things to watch in day-to-day operation

• Escaping on output: Since ACF 6.2.7 (2024), the_field() strips unsafe HTML, but it does not handle attribute or URL contexts. Retrieve values with get_field() and use esc_html(), esc_attr(), esc_url() and wp_kses_post() as appropriate.
• Renaming fields: If you rename a field after launch, you can no longer retrieve the existing values.
• Number of lookups on archive pages: Calling get_field() many times per post on an archive increases metadata loading. Fetch only the fields you need, and don't call values you won't display inside the loop.
• Back up before updating: Before a major update, or before switching between ACF and SCF, back up the database and files and check on staging.

Summary

• Since October 2024, ACF and SCF exist as separate plugins. Know which one your site uses and where it receives updates from.
• If you need Repeater, options pages or ACF Blocks, consider PRO (or an alternative with equivalent features).
• Choose where to store data: site-wide values on an options page, per-block display with ACF Blocks, and values used for searching or sorting as post meta.
• Manage field definitions in Git with Local JSON and only sync on production, which keeps environments from drifting apart.
• Enable REST API display per group, keeping in mind who can see it.

• ACF Basics: From Creating Fields to Displaying Them in Templates
• How to Manage ACF Field Groups with JSON

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)