How to Build ACF Field Groups

3 min read by Mohammad Shoeb

How to Build ACF Field Groups

ACF field groups are how you attach custom fields to your WordPress content in Advanced Custom Fields. A field group is a collection of fields plus location rules that decide where the group appears, such as a specific post type, page template, or taxonomy term. Get the structure right and your custom data stays clean, predictable, and easy to query. Here is how to build ACF field groups properly.

What a field group actually is

A field group bundles related fields together and uses location rules to control where they show up in the editor. You might attach a group to the “Page” post type, to pages using a “Landing Page” template, or to a specific taxonomy. Multiple rules can be combined with AND/OR logic, so one group can target several contexts at once.

The fastest way to plan one is the ACF Field Group Builder, which lets you map out fields and location rules visually before you commit anything to the database.

Common field types

ACF ships with a wide range of field types. The ones you will reach for most often:

  • Text and Textarea: short strings and longer plain text.
  • Image: returns an attachment ID, URL, or array.
  • True / False: a simple boolean toggle.
  • Relationship: link a field to other posts, pages, or custom post types.
  • Repeater: a repeatable set of subfields, ideal for lists like team members or FAQs.
  • Flexible Content: a layout builder where editors pick from predefined blocks. This is the heaviest field type and the most powerful for page building.

Pick the simplest type that fits the data. Reach for Repeater and Flexible Content only when you genuinely need repeating or modular layouts.

Naming conventions that prevent collisions

Field names are the keys you use in code, so be deliberate. Use lowercase_with_underscores, and prefix names to avoid collisions with other plugins or themes. A field called subtitle is risky; mytheme_hero_subtitle is safe. Keep names descriptive and consistent across groups so your templates stay readable.

To build a group with clean names from the start:

  1. Open the ACF Field Group Builder and name your group.
  2. Add each field, choosing its type and a prefixed, lowercase_with_underscores name.
  3. Set the location rules for the post type, template, or taxonomy you are targeting.
  4. Export the configuration to register in code or sync as JSON.

Retrieving values in your templates

Once fields hold data, two functions do most of the work. get_field('field_name') returns the value so you can store or process it, and the_field('field_name') echoes it directly. Use get_field() when you need to check or transform the value first, and the_field() for quick output. For Repeater and Flexible Content fields, loop with have_rows() and the_row() to walk each row.

Version control with acf-json

Storing field groups only in the database makes them invisible to Git and painful to move between environments. The modern best practice is to register field groups in code or let ACF sync them to JSON. Create an acf-json folder in your theme, and ACF will automatically write each field group to a .json file when you save it. Those files are committed alongside your code, so every environment stays in sync and you get a clean history of every change. You can also load groups programmatically with acf_add_local_field_group() if you prefer pure PHP.

Plan the group, name fields carefully, query with get_field(), and let acf-json keep it all in version control.

WordPressDeveloper ToolsHow-to

← All posts