How to Use the Group Field in Advanced Custom Fields

The Group field in ACF allows you to organize multiple sub-fields under a single parent, making your WordPress admin cleaner and your field logic more maintainable. It’s perfect for grouping related fields, especially when working with complex layouts or custom templates.

Unlike a Repeater field, the Group field does not allow multiple rows, it represents a single set of related sub-fields grouped together.

In this post, you’ll learn what the Group field does, when and why to use it, how to display its data in your theme, and best practices for structured field architecture.

What Is the Group Field in ACF?

The Group field is a container that holds multiple sub-fields, such as text, images, selects, etc., under one parent key. It keeps your field groups organized and prevents clutter when assigning many fields to a post, page, or custom post type.

• Group fields are not repeatable
• They can contain any ACF field type
• They return data as a nested associative array

When Should You Use a Group Field?

Use Group fields when you want to logically bundle related information together. Here are a few examples:

• Contact information (phone, email, address)
• Hero section settings (title, image, CTA)
• Card data (icon, title, description)

Grouping improves both user experience in the admin and clarity when accessing the data in your templates.

How to Add a Group Field in ACF

To create a group field:

1. Go to Custom Fields › Field Groups and edit or create a group
2. Add a new field and choose Group as the type
3. Inside the Group field, add your sub-fields
4. Save the field group and assign it to a post type or page

Displaying Group Field Data in Your Theme

Group fields return an array. To output a sub-field, you first get the group, then extract sub-values from it. Here’s an example with a group field called hero_section that contains a title, subtitle, and background image:

<?php
$hero = get_field('hero_section');
if ( $hero ) :
    $title = $hero['title'];
    $subtitle = $hero['subtitle'];
    $image = $hero['background_image'];
?>
    <section class="hero" style="background-image: url('<?php echo esc_url($image['url']); ?>');">
        <h1><?php echo esc_html($title); ?></h1>
        <p><?php echo esc_html($subtitle); ?></p>
    </section>
<?php endif; ?>

This method keeps your code clean and efficient, especially when dealing with grouped UI sections.

Tip: The Advanced Custom Fields: Theme Code Pro plugin helps you work faster by automatically generating ready-to-use PHP code for your ACF fields.

Using Group Fields Inside Repeaters

You can also use Group fields inside Repeater rows to structure more complex data. For example, if each team member has a name, role, and contact info, you can structure it like this:

<?php
if ( have_rows('team_members') ): ?>
    <ul>
        <?php while ( have_rows('team_members') ): the_row();
            $person = get_sub_field('person_info');
            $name = $person['name'];
            $role = $person['role'];
            $email = $person['email'];
        ?>
        <li>
            <strong><?php echo esc_html($name); ?></strong> – <?php echo esc_html($role); ?> (
            <a href="mailto:<?php echo esc_attr($email); ?>"><?php echo esc_html($email); ?></a>)
        </li>
        <?php endwhile; ?>
    </ul>
<?php endif; ?>

This is a great way to keep nested data structured and reduce field duplication.

Group vs Repeater vs Flexible Content

Advanced Custom Fields offers multiple ways to structure content, each suited for different use cases. Understanding the difference between Group, Repeater, and Flexible Content fields is key to choosing the right tool for your data model.

• Group: A single, structured set of related fields.
  Use it for things like a hero_section with a title, subtitle, and image.
• Repeater: A repeatable set of the same fields.
  Perfect for dynamic lists like team members, FAQs, or services.
• Flexible Content: Multiple layout options with different field structures.
  Use it for building custom content blocks like image + text, galleries, or CTAs.

Use a Group when you need one structured set. Use a Repeater when you need many. Use Flexible Content when the structure itself needs to vary.

Admin UI Tips

Well-organized fields in the WordPress admin improve the content editor’s experience and reduce confusion. Group fields, in particular, offer ways to streamline the interface—here’s how to make the most of them:

• Give each sub-field a clear, descriptive label: Avoid vague names like “Text” or “Image.” Instead, use labels like “Hero Title” or “Team Member Photo” to make their purpose obvious.
• Use the “Block” layout option: When creating a Group field, set the layout to Block so sub-fields are displayed inside a visually distinct box with padding. This helps editors visually identify that the fields belong together.
• Collapse long or advanced groups: Use the “Instructions Placement” and “Wrapper Attributes” to create collapsible groups or add visual separation between field sections. This is especially helpful when working with many groups on a single page.

Think like a content editor: organize fields not just for backend logic, but for clarity and usability in the admin panel.

Conclusion

ACF’s Group field is a powerful feature for organizing related data into a single structured array. Whether you use it for clean UI sections, nested repeatable structures, or better field management, it enhances both developer control and content editor usability.

Want to explore more dynamic ACF use cases? Check out our list of ACF related guides.