The Beginner's Guide to Advanced Custom Fields
Everything you need to know about ACF: what it is, how to install it, and how to use it to build custom WordPress sites. The most comprehensive ACF beginner's guide on the web.
What Is Advanced Custom Fields?
Advanced Custom Fields, or ACF for short, is the most widely used custom fields plugin for WordPress. It gives designers and developers a standardised collection of field types for adding structured data to posts, pages, users, taxonomies, and options pages. Instead of typing everything into a single content editor, ACF lets you break content into discrete, manageable fields that are easier to enter, validate, and display.
ACF is a tool for three things:
- Enhancing the content editing experience — giving site administrators clear, labelled inputs instead of freeform text.
- Structuring data as it's stored — each piece of information goes into its own database field, making it queryable and portable.
- Displaying data reliably on the frontend — ACF provides PHP template functions that give you clean, predictable access to your custom field values.
ACF is developed and maintained by WP Engine. The free version is available on wordpress.org, and it's trusted by hundreds of thousands of WordPress professionals worldwide.
A note on ACF vs SCF
In late 2024, a fork called Secure Custom Fields (SCF) was created during the WP Engine/Automattic dispute. WP Engine regained control of the ACF listing on wordpress.org in December 2024. ACF remains the original, actively maintained product. SCF exists as a community-maintained fork, but ACF is the plugin this guide (and this entire site) is built around.
ACF Free vs ACF Pro: What's the Difference?
The free version covers the essentials and is genuinely powerful. ACF Pro adds the features most professionals consider indispensable:
| Feature | Free | Pro |
|---|---|---|
| Repeater Field | — | ✓ |
| Flexible Content | — | ✓ |
| Gallery Field | — | ✓ |
| Options Pages | — | ✓ |
| ACF Blocks | — | ✓ |
| Clone Field | — | ✓ |
Who Is ACF Built For?
When I first discovered ACF, it was a pivotal moment. I remember thinking of all the possibilities that were now open to me as a freelance web developer. Fast forward many years and I'm still using it in just about every WordPress project I'm involved in. It saves me time and provides my clients with admin experiences that would take ages to build from scratch.
For Developers
ACF is a robust set of custom fields with a stable API for storing and retrieving metadata. You get get_field(), the_field(), and helper functions that work consistently across post types, taxonomies, users, and options pages.
For Designers
ACF is a way to move beyond standard WordPress templates into complex layouts with structured data. You work mostly within HTML, CSS, and minimal PHP while providing clients with websites that structure and display data cleanly.
ACF Field Types: A Complete Overview
ACF ships with over 30 built-in field types, and there's a growing ecosystem of third-party field types developed by independent developers around the world.
Core Field Types Free
- •Text fields — single line, textarea, and WYSIWYG editor
- •Choice fields — select, checkbox, radio, button group, true/false
- •Content fields — image, file, oEmbed, WYSIWYG
- •Relational fields — post object, page link, relationship, taxonomy
- •Layout fields — accordion, tab, group, message
- •Utility fields — date, time, colour picker, Google Maps, number
Pro Field Types Pro
- •Repeater — sets of sub-fields repeated any number of times (team members, pricing tiers)
- •Flexible Content — multiple layout types editors mix and match for page sections
- •Gallery — ordered image collections with drag-and-drop
- •Clone — reuse fields and groups without duplication
These Pro fields are the backbone of most professional ACF projects. The repeater and flexible content fields in particular are what make ACF a genuine page builder toolkit for developers.
How to Install and Set Up ACF
Installing ACF Free
- 1In your WordPress dashboard, go to Plugins → Add New
- 2Search for "Advanced Custom Fields"
- 3Click Install Now, then Activate
- 4You'll see a new ACF menu item in the sidebar
Upgrading to ACF Pro
- 1Purchase a licence from advancedcustomfields.com
- 2Download the Pro plugin ZIP from your account
- 3Deactivate ACF Free (Pro includes everything)
- 4Upload and activate via Plugins → Upload Plugin
- 5Enter your licence key under ACF → Updates
Tip: You can store your ACF Pro licence key in wp-config.php to avoid entering it manually on each site. See our licence key snippet.
Creating Your First Field Group
A field group is a collection of fields that you assign to a specific location in the WordPress admin, such as a post type, page template, taxonomy, or user profile.
Adding Fields
- Go to ACF → Field Groups → Add New
- Give your field group a name (e.g., "Project Details")
- Click Add Field and choose a field type
- Configure the field: set its label, name (used in code), instructions for editors, and field-specific settings
- Repeat for each field you need
The field name is what you'll use in your theme templates to retrieve the value. Keep them lowercase with underscores: project_client, project_budget, project_start_date.
Setting Location Rules
Below your fields, the Location Rules panel controls where the field group appears. You can target:
Rules can be combined with AND/OR logic. For example: post_type == project AND user_role == administrator.
Using Conditional Logic
Individual fields can be shown or hidden based on other field values. For example, show a "Budget Details" textarea only when a "Has Budget" true/false field is checked. This keeps the editing interface clean and focused for content editors.
Displaying ACF Data in Your Theme
This is where ACF connects the admin experience to your frontend templates. ACF provides a small set of PHP functions you'll use constantly.
Basic Template Functions
The two functions you'll use most are get_field() and the_field():
// Get a field value (returns the value for use in logic)
$client = get_field('project_client');
// Echo a field value directly
the_field('project_client');A typical template pattern with a conditional check:
<?php if ( get_field('project_client') ) : ?>
<div class="project-meta">
<h3>Client</h3>
<p><?php the_field('project_client'); ?></p>
</div>
<?php endif; ?>Working with Repeater Fields Pro
Repeater fields use a loop pattern similar to WordPress's have_posts():
<?php if ( have_rows('team_members') ) : ?>
<ul class="team-list">
<?php while ( have_rows('team_members') ) : the_row(); ?>
<li>
<h4><?php the_sub_field('name'); ?></h4>
<p><?php the_sub_field('role'); ?></p>
</li>
<?php endwhile; ?>
</ul>
<?php endif; ?>Save time with ACF Theme Code Pro. Instead of writing template code from scratch, ACF Theme Code Pro generates PHP snippets for any field group. Just copy, paste, and add your HTML. There's also a free version on wordpress.org.
Key ACF Features for Developers
Beyond field types and template functions, ACF has several features that make it a serious developer tool.
ACF Blocks (Gutenberg Integration)
ACF Blocks lets you register custom block types for the WordPress Block Editor without writing any JavaScript or React. You define a block with PHP, assign ACF fields to it, and write a PHP template to render it. The admin preview updates live as editors fill in the fields.
This is one of ACF's most powerful features for agencies building client sites. Browse our Gutenberg block extensions for ready-made block libraries, or see the ACF Blocks documentation.
Options Pages Pro
Custom options pages let you place ACF fields for site-wide settings like global defaults, footer content, social media URLs, and company information. Data is stored in wp_options and retrieved with:
$phone = get_field('company_phone', 'option');Frontend Forms
ACF includes acf_form() for rendering field groups on the frontend, which is useful for user-submitted content, frontend dashboards, or restricted editing interfaces. For more control including user creation, email notifications, and integrations, check out Advanced Forms Pro from Hookturn.
Local JSON
ACF can save field group configurations as JSON files in your theme, which is a game-changer for version control. Instead of field groups living only in the database, they're tracked in Git alongside your code.
Create an acf-json folder in your theme directory and ACF will automatically save JSON files there. Read our guide: ACF Local JSON Introduction. Also see: Load JSON from multiple locations and Force JSON generation for all field groups.
Extending ACF with Third-Party Plugins
One of ACF's greatest strengths is its extensibility. There are 240+ third-party extensions that add new capabilities:
Field Types
Colour pickers, maps, sliders, font selectors
Admin UI
Field group management and admin layouts
Developer Tools
Debugging, migration, and workflow utilities
Integration
WooCommerce, Elementor, Gravity Forms
For sites with large datasets, ACF Custom Database Tables moves ACF data into dedicated database tables for dramatically improved query performance. Read more: Storing ACF Data in Custom Database Tables.
What ACF Is Not For
ACF is incredibly flexible, but it's not the right tool for everything. Being honest about its limits saves you time:
Contact forms (on its own)
ACF's built-in acf_form() is designed for content editing, not visitor-facing contact forms. However, the Advanced Forms plugin (free) bridges this gap by letting you build contact forms using ACF fields with email notifications, spam protection, and entry storage.
Replacing WooCommerce product data
WooCommerce has its own product fields system. ACF can supplement it by adding custom fields to products, but it shouldn't replace WooCommerce's core product data like pricing, inventory, and variations.
Complex application logic
ACF is a data layer, not an application framework. For complex business logic, you'll need custom PHP alongside ACF.
Frequently Asked Questions
What is the ACF plugin used for?
ACF (Advanced Custom Fields) is used to add structured custom fields to WordPress content. Instead of putting all content into a single editor, ACF lets you create specific input fields (text, images, selects, relationships, repeaters, and more) that make content entry cleaner for editors and data retrieval more reliable for developers.
What is the difference between ACF and ACF Pro?
ACF Free includes 30+ field types and covers most basic custom field needs. ACF Pro adds the Repeater field, Flexible Content field, Gallery field, Options Pages, ACF Blocks (Gutenberg integration), and the Clone field. For professional WordPress development, ACF Pro is considered essential. The repeater and flexible content fields alone are used in the majority of professional ACF projects.
How do I use Advanced Custom Fields with WooCommerce?
Create a field group and set the location rule to Post Type equals Product. Your custom fields will appear alongside WooCommerce's default product data. Use get_field() in your product templates to display the values. This is useful for adding specifications, custom attributes, or supplementary content that doesn't fit into WooCommerce's standard fields.
What is the difference between ACF and Elementor?
ACF is a data layer that adds structured custom fields and provides PHP functions to display that data. Elementor is a visual page builder with drag-and-drop frontend editing. They can work together: ACF manages structured data while Elementor builds the visual layout, pulling ACF field values via dynamic tags.
Is ACF still actively maintained?
Yes. ACF is actively developed by WP Engine with regular updates, security patches, and new features. It remains the most widely used custom fields plugin for WordPress. The plugin should not be confused with SCF (Secure Custom Fields), a community fork created during the 2024 WP Engine/Automattic dispute. ACF is the original, actively maintained product.
Stay Updated
Get ACF tips and new extensions in your inbox
No spam. Unsubscribe anytime.