Creating ACF Pro field groups

Goal

By the end of this guide, you'll have an ACF Pro Flexible Content field group configured and ready to use with Divi Handoff Layouts.

Prerequisites

• Divi Handoff installed and activated
• ACF Pro installed and activated
• WordPress admin access

ACF Pro Required

Only ACF Pro is supported. The free version of ACF does not include the Flexible Content field type, which is required for Divi Handoff.

If you need a free alternative, use SCF (Secure Custom Fields) instead—it includes Flexible Content at no cost.

Steps

Step 1: Access ACF Pro field groups

1. Navigate to ACF → Field Groups in the WordPress admin menu
2. Click Add New to create a new field group

Step 2: Name your field group

1. Enter a descriptive title (e.g., "Homepage Sections" or "Service Page Content")
2. This name is for admin reference only and won't appear on the frontend

Step 3: Set location rules

Configure where this field group appears:

1. Scroll to the Settings section
2. Under Location Rules, set conditions for when the fields appear
3. Common configurations:
   • Post Type is equal to Page (for all pages)
   • Page Template is equal to Default Template (for specific templates)
   • Post is equal to Homepage (for a specific page)

tip

Start with a broad rule like "Post Type is equal to Page" while learning. You can refine the targeting later.

Step 4: Add a Flexible Content field

1. Click + Add Field in the Fields section
2. Set the Field Type to Flexible Content
3. Configure the field:
   • Field Label: Enter a descriptive name (e.g., "Page Sections")
   • Field Name: ACF auto-generates this from the label (e.g., page_sections)
   • Button Label: Customize the "Add Row" button text (e.g., "Add Section")

Step 5: Create layouts within Flexible Content

Layouts are the building blocks content editors will add to pages. Each layout represents a different type of content section.

1. Click Add Layout within the Flexible Content field
2. Configure the layout:
   • Label: The name shown to editors (e.g., "Hero Section")
   • Name: The machine name used by Divi Handoff (e.g., hero_section)
3. Repeat for each section type you need:
   • Hero Section
   • Text Block
   • Image Gallery
   • Team Member
   • Call to Action
   • Testimonial

Step 6: Add sub-fields to each layout

Each layout needs sub-fields that define what content editors can enter:

1. Click on a layout to expand it
2. Click + Add Sub Field
3. Add appropriate fields for that layout type

Example: Hero Section layout

Field Label	Field Type	Field Name	Notes
Heading	Text	heading	Main hero title
Subheading	Text	subheading	Supporting text
Description	Textarea	description	Longer content
Background Image	Image	background_image	Return Format: Image URL
Button Text	Text	button_text	CTA button label
Button Link	URL	button_link	CTA destination

Example: Team Member layout

Field Label	Field Type	Field Name	Notes
Photo	Image	photo	Return Format: Image URL
Name	Text	name	Team member name
Job Title	Text	job_title	Position/role
Bio	Textarea	bio	Short biography
Email	Email	email	Contact email
LinkedIn	URL	linkedin	Social profile link

Step 7: Configure image field return format

For image fields to work correctly with Divi Handoff:

1. Click on an Image field to edit it
2. Find Return Format setting
3. Select Image URL for simplest integration
4. Alternatively, select Image Array for access to alt text and sizes

note

Using Image URL return format provides the most straightforward integration with Handoff Image modules. The module receives the URL directly without additional processing.

Step 8: Publish the field group

1. Review your field group configuration
2. Click Publish or Update to save
3. Navigate to a page matching your location rules to verify the fields appear

Verification

To confirm your setup works:

1. Go to Pages → Add New (or edit an existing page matching your rules)
2. Scroll below the editor to find your field group
3. Click Add Section (or your custom button label)
4. Verify all layouts appear and sub-fields are accessible
5. Enter some test content and save the page

ACF Pro vs SCF differences

If you're familiar with SCF, here are the key differences when using ACF Pro:

Aspect	ACF Pro	SCF
Cost	Paid license	Free
Menu Location	ACF → Field Groups	SCF → Field Groups
Interface	Modern, polished UI	Similar to classic ACF
Field Types	More field types available	Core field types
Flexible Content	✅ Included	✅ Included
Divi Handoff Support	✅ Full support	✅ Full support

Both plugins work identically with Divi Handoff—the field names and data structures are compatible.

Best practices

Naming conventions

• Field names: Use lowercase with underscores (e.g., hero_heading, team_photo)
• Layout names: Use descriptive, lowercase names (e.g., hero_section, team_member)
• Field labels: Use clear, user-friendly names editors will understand

Organization tips

• Group related layouts logically
• Use consistent field naming patterns across layouts
• Add Instructions to fields to guide content editors
• Use Placeholder text to show expected format
• Set Required on essential fields

Performance considerations

• Avoid deeply nested repeaters (keep to 2 levels maximum)
• Use appropriate image sizes rather than full resolution
• Limit the number of layouts to what's actually needed

Troubleshooting

Fields not appearing on page

• Verify Location Rules match the page you're editing
• Check that the field group is Published (not Draft)
• Clear any caching plugins

Image fields showing as ID instead of URL

• Edit the Image field
• Change Return Format to Image URL
• Re-save any existing content

Flexible Content button not showing

• Ensure you have at least one layout defined
• Check that the Flexible Content field itself is not hidden by conditional logic

What's Next

• Creating SCF Field Groups - Alternative free option for Flexible Content
• Creating Handoff Layouts - Build Divi layouts that use your field groups
• Quick Start Guide - Complete end-to-end setup walkthrough