Integrating ACF with WPGraphQL for Maximum Flexibility
Advanced Custom Fields (ACF) transforms WordPress into a flexible content management system, while WPGraphQL provides a modern API layer. Together, they create a powerful combination for headless WordPress development, enabling complex content structures with type-safe GraphQL queries.
This guide covers everything from basic setup to advanced integration patterns, helping you leverage ACF and WPGraphQL to build sophisticated headless applications with complex data requirements.
Table of Contents
- Setup and Configuration
- Field Types and GraphQL Mapping
- Complex Field Groups
- Custom Resolvers and Types
- Performance Optimization
- Real-World Examples
- Best Practices
Setup and Configuration
Installing Required Plugins
# Via WP-CLI
wp plugin install advanced-custom-fields --activate
wp plugin install wp-graphql --activate
wp plugin install wpgraphql-acf --activate
# Or manually download from:
# - https://wordpress.org/plugins/advanced-custom-fields/
# - https://github.com/wp-graphql/wp-graphql
# - https://github.com/wp-graphql/wpgraphql-acf
Basic Configuration
// functions.php - Enable ACF fields in GraphQL
add_action('acf/init', function() {
// Ensure ACF fields show in GraphQL
if (!function_exists('acf_add_options_page')) {
return;
}
// Add theme options page
acf_add_options_page([
'page_title' => 'Theme Options',
'menu_title' => 'Theme Options',
'menu_slug' => 'theme-options',
'capability' => 'edit_posts',
'show_in_graphql' => true,
'graphql_field_name' => 'themeOptions'
]);
});
// Configure ACF to save JSON files
add_filter('acf/settings/save_json', function($path) {
return get_stylesheet_directory() . '/acf-json';
});
add_filter('acf/settings/load_json', function($paths) {
unset($paths[0]);
$paths[] = get_stylesheet_directory() . '/acf-json';
return $paths;
});
GraphQL Configuration
// Enable GraphQL debugging in development
add_action('graphql_init', function() {
if (WP_DEBUG) {
define('GRAPHQL_DEBUG', true);
}
});
// Increase GraphQL query depth limit
add_filter('graphql_request_max_query_depth', function($depth) {
return 15; // Default is 10
});
Field Types and GraphQL Mapping
Basic Field Types
// ACF field group registration with GraphQL support
if (function_exists('acf_add_local_field_group')) {
acf_add_local_field_group([
'key' => 'group_article_fields',
'title' => 'Article Fields',
'fields' => [
// Text field
[
'key' => 'field_subtitle',
'label' => 'Subtitle',
'name' => 'subtitle',
'type' => 'text',
'show_in_graphql' => true,
'graphql_field_name' => 'subtitle'
],
// Textarea
[
'key' => 'field_summary',
'label' => 'Summary',
'name' => 'summary',
'type' => 'textarea',
'rows' => 4,
'show_in_graphql' => true,
'graphql_field_name' => 'summary'
],
// Number field
[
'key' => 'field_reading_time',
'label' => 'Reading Time (minutes)',
'name' => 'reading_time',
'type' => 'number',
'min' => 1,
'max' => 60,
'show_in_graphql' => true,
'graphql_field_name' => 'readingTime'
],
// Select field
[
'key' => 'field_difficulty',
'label' => 'Difficulty Level',
'name' => 'difficulty',
'type' => 'select',
'choices' => [
'beginner' => 'Beginner',
'intermediate' => 'Intermediate',
'advanced' => 'Advanced'
],
'show_in_graphql' => true,
'graphql_field_name' => 'difficultyLevel'
],
// True/False field
[
'key' => 'field_featured',
'label' => 'Featured Article',
'name' => 'is_featured',
'type' => 'true_false',
'show_in_graphql' => true,
'graphql_field_name' => 'isFeatured'
]
],
'location' => [
[
[
'param' => 'post_type',
'operator' => '==',
'value' => 'post'
]
]
],
'show_in_graphql' => true,
'graphql_field_name' => 'articleFields'
]);
}
GraphQL Query for Basic Fields
query GetArticleWithACF($id: ID!) {
post(id: $id) {
id
title
content
articleFields {
subtitle
summary
readingTime
difficultyLevel
isFeatured
}
}
}
Advanced Field Types
// Image and media fields
[
'key' => 'field_hero_image',
'label' => 'Hero Image',
'name' => 'hero_image',
'type' => 'image',
'return_format' => 'array',
'preview_size' => 'medium',
'show_in_graphql' => true,
'graphql_field_name' => 'heroImage'
],
// File field
[
'key' => 'field_download',
'label' => 'Downloadable Resource',
'name' => 'download_file',
'type' => 'file',
'return_format' => 'array',
'show_in_graphql' => true,
'graphql_field_name' => 'downloadFile'
],
// Date picker
[
'key' => 'field_event_date',
'label' => 'Event Date',
'name' => 'event_date',
'type' => 'date_picker',
'display_format' => 'F j, Y',
'return_format' => 'Y-m-d',
'show_in_graphql' => true,
'graphql_field_name' => 'eventDate'
],
// Color picker
[
'key' => 'field_brand_color',
'label' => 'Brand Color',
'name' => 'brand_color',
'type' => 'color_picker',
'default_value' => '#2271b1',
'show_in_graphql' => true,
'graphql_field_name' => 'brandColor'
],
// URL field
[
'key' => 'field_external_link',
'label' => 'External Link',
'name' => 'external_link',
'type' => 'url',
'show_in_graphql' => true,
'graphql_field_name' => 'externalLink'
]
Complex Field Groups
Repeater Fields
// Team members repeater
[
'key' => 'field_team_members',
'label' => 'Team Members',
'name' => 'team_members',
'type' => 'repeater',
'show_in_graphql' => true,
'graphql_field_name' => 'teamMembers',
'layout' => 'block',
'button_label' => 'Add Team Member',
'sub_fields' => [
[
'key' => 'field_member_name',
'label' => 'Name',
'name' => 'name',
'type' => 'text',
'required' => true,
'show_in_graphql' => true,
'graphql_field_name' => 'name'
],
[
'key' => 'field_member_role',
'label' => 'Role',
'name' => 'role',
'type' => 'text',
'show_in_graphql' => true,
'graphql_field_name' => 'role'
],
[
'key' => 'field_member_photo',
'label' => 'Photo',
'name' => 'photo',
'type' => 'image',
'return_format' => 'array',
'show_in_graphql' => true,
'graphql_field_name' => 'photo'
],
[
'key' => 'field_member_bio',
'label' => 'Bio',
'name' => 'bio',
'type' => 'textarea',
'rows' => 3,
'show_in_graphql' => true,
'graphql_field_name' => 'bio'
]
]
]
Flexible Content Fields
// Page builder with flexible content
[
'key' => 'field_page_sections',
'label' => 'Page Sections',
'name' => 'page_sections',
'type' => 'flexible_content',
'show_in_graphql' => true,
'graphql_field_name' => 'pageSections',
'button_label' => 'Add Section',
'layouts' => [
// Hero section
[
'key' => 'layout_hero',
'name' => 'hero_section',
'label' => 'Hero Section',
'show_in_graphql' => true,
'graphql_field_name' => 'HeroSection',
'sub_fields' => [
[
'key' => 'field_hero_title',
'label' => 'Title',
'name' => 'title',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_hero_subtitle',
'label' => 'Subtitle',
'name' => 'subtitle',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_hero_background',
'label' => 'Background Image',
'name' => 'backgroundImage',
'type' => 'image',
'return_format' => 'array',
'show_in_graphql' => true
]
]
],
// Content section
[
'key' => 'layout_content',
'name' => 'content_section',
'label' => 'Content Section',
'show_in_graphql' => true,
'graphql_field_name' => 'ContentSection',
'sub_fields' => [
[
'key' => 'field_content_title',
'label' => 'Title',
'name' => 'title',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_content_body',
'label' => 'Content',
'name' => 'content',
'type' => 'wysiwyg',
'show_in_graphql' => true
],
[
'key' => 'field_content_columns',
'label' => 'Columns',
'name' => 'columns',
'type' => 'select',
'choices' => [
'1' => '1 Column',
'2' => '2 Columns',
'3' => '3 Columns'
],
'default_value' => '1',
'show_in_graphql' => true
]
]
],
// Gallery section
[
'key' => 'layout_gallery',
'name' => 'gallery_section',
'label' => 'Gallery Section',
'show_in_graphql' => true,
'graphql_field_name' => 'GallerySection',
'sub_fields' => [
[
'key' => 'field_gallery_title',
'label' => 'Title',
'name' => 'title',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_gallery_images',
'label' => 'Images',
'name' => 'images',
'type' => 'gallery',
'return_format' => 'array',
'show_in_graphql' => true
]
]
]
]
]
GraphQL Query for Complex Fields
query GetPageWithSections($id: ID!) {
page(id: $id) {
id
title
pageSections {
__typename
... on HeroSection {
title
subtitle
backgroundImage {
sourceUrl
altText
mediaDetails {
width
height
}
}
}
... on ContentSection {
title
content
columns
}
... on GallerySection {
title
images {
id
sourceUrl
altText
caption
}
}
}
}
}
Relationship Fields
// Related posts field
[
'key' => 'field_related_posts',
'label' => 'Related Posts',
'name' => 'related_posts',
'type' => 'relationship',
'post_type' => ['post'],
'filters' => ['search', 'taxonomy'],
'return_format' => 'id',
'show_in_graphql' => true,
'graphql_field_name' => 'relatedPosts'
],
// Post object field
[
'key' => 'field_featured_case_study',
'label' => 'Featured Case Study',
'name' => 'featured_case_study',
'type' => 'post_object',
'post_type' => ['case_study'],
'return_format' => 'id',
'show_in_graphql' => true,
'graphql_field_name' => 'featuredCaseStudy'
],
// User field
[
'key' => 'field_article_reviewer',
'label' => 'Article Reviewer',
'name' => 'article_reviewer',
'type' => 'user',
'role' => ['editor', 'administrator'],
'return_format' => 'id',
'show_in_graphql' => true,
'graphql_field_name' => 'articleReviewer'
]
Custom Resolvers and Types
Creating Custom GraphQL Types
// Register custom GraphQL type for complex ACF data
add_action('graphql_register_types', function() {
// Register custom object type
register_graphql_object_type('ProductSpecification', [
'description' => 'Product specification details',
'fields' => [
'weight' => [
'type' => 'Float',
'description' => 'Product weight in kg'
],
'dimensions' => [
'type' => 'String',
'description' => 'Product dimensions (LxWxH)'
],
'material' => [
'type' => 'String',
'description' => 'Primary material'
],
'warranty' => [
'type' => 'Int',
'description' => 'Warranty period in months'
]
]
]);
// Add field to Product type
register_graphql_field('Product', 'specifications', [
'type' => 'ProductSpecification',
'description' => 'Product specifications',
'resolve' => function($product) {
$specs = get_field('product_specifications', $product->ID);
if (!$specs) {
return null;
}
return [
'weight' => floatval($specs['weight']),
'dimensions' => $specs['dimensions'],
'material' => $specs['material'],
'warranty' => intval($specs['warranty_period'])
];
}
]);
});
Custom Field Resolvers
// Add computed fields based on ACF data
add_action('graphql_register_types', function() {
// Add reading time calculation
register_graphql_field('Post', 'estimatedReadingTime', [
'type' => 'Int',
'description' => 'Estimated reading time in minutes',
'resolve' => function($post) {
$content = get_field('article_content', $post->ID) ?: $post->post_content;
$word_count = str_word_count(strip_tags($content));
$reading_speed = 200; // words per minute
return ceil($word_count / $reading_speed);
}
]);
// Add dynamic pricing field
register_graphql_field('Product', 'currentPrice', [
'type' => 'Float',
'description' => 'Current price including any discounts',
'resolve' => function($product) {
$base_price = get_field('base_price', $product->ID);
$discount_percentage = get_field('discount_percentage', $product->ID) ?: 0;
if ($discount_percentage > 0) {
return $base_price * (1 - $discount_percentage / 100);
}
return $base_price;
}
]);
// Add formatted address field
register_graphql_field('Location', 'formattedAddress', [
'type' => 'String',
'description' => 'Complete formatted address',
'resolve' => function($location) {
$address_fields = get_field('address', $location->ID);
if (!$address_fields) {
return null;
}
$parts = array_filter([
$address_fields['street'],
$address_fields['city'],
$address_fields['state'],
$address_fields['zip'],
$address_fields['country']
]);
return implode(', ', $parts);
}
]);
});
Batch Loading and DataLoader Pattern
// Implement DataLoader pattern for efficient ACF queries
class ACFDataLoader {
private static $instance = null;
private $loader_cache = [];
public static function getInstance() {
if (self::$instance === null) {
self::$instance = new self();
}
return self::$instance;
}
public function loadFieldsForPosts($post_ids, $field_names) {
$cache_key = md5(serialize($post_ids) . serialize($field_names));
if (isset($this->loader_cache[$cache_key])) {
return $this->loader_cache[$cache_key];
}
// Batch load all fields for all posts
$results = [];
foreach ($post_ids as $post_id) {
$results[$post_id] = [];
foreach ($field_names as $field_name) {
$results[$post_id][$field_name] = get_field($field_name, $post_id);
}
}
$this->loader_cache[$cache_key] = $results;
return $results;
}
}
// Use in resolver
add_action('graphql_register_types', function() {
register_graphql_field('Post', 'batchedACFFields', [
'type' => 'String',
'resolve' => function($post, $args, $context, $info) {
$loader = ACFDataLoader::getInstance();
// Collect all post IDs from current query
$post_ids = [$post->ID]; // In real implementation, collect from context
$field_names = ['field1', 'field2', 'field3'];
$data = $loader->loadFieldsForPosts($post_ids, $field_names);
return json_encode($data[$post->ID]);
}
]);
});
Performance Optimization
Lazy Loading ACF Fields
// Only load ACF fields when requested in GraphQL
add_filter('graphql_resolve_field', function($result, $source, $args, $context, $info) {
// Check if this is an ACF field
if (!str_starts_with($info->fieldName, 'acf')) {
return $result;
}
// Implement lazy loading
if ($result === null) {
$field_name = str_replace('acf_', '', $info->fieldName);
$result = get_field($field_name, $source->ID);
}
return $result;
}, 10, 5);
Caching ACF Queries
// Cache ACF field groups
add_filter('acf/load_field_group', function($field_group) {
$cache_key = 'acf_field_group_' . $field_group['key'];
$cached = wp_cache_get($cache_key);
if ($cached !== false) {
return $cached;
}
wp_cache_set($cache_key, $field_group, '', HOUR_IN_SECONDS);
return $field_group;
});
// Cache complex ACF queries
function get_cached_acf_data($post_id, $field_name) {
$cache_key = "acf_{$post_id}_{$field_name}";
$cached = wp_cache_get($cache_key, 'acf_fields');
if ($cached !== false) {
return $cached;
}
$value = get_field($field_name, $post_id);
wp_cache_set($cache_key, $value, 'acf_fields', 15 * MINUTE_IN_SECONDS);
return $value;
}
Query Optimization
// Optimize ACF queries for GraphQL
add_filter('graphql_post_object_connection_query_args', function($query_args, $source, $args, $context, $info) {
// Pre-load ACF fields to avoid N+1 queries
if (isset($args['where']['metaQuery'])) {
$query_args['meta_query'] = $args['where']['metaQuery'];
}
// Optimize for specific field requests
$selection_set = $info->getFieldSelection();
if (isset($selection_set['edges']['node']['acfFields'])) {
// Pre-cache ACF data
add_filter('the_posts', function($posts) {
$post_ids = wp_list_pluck($posts, 'ID');
update_meta_cache('post', $post_ids);
return $posts;
});
}
return $query_args;
}, 10, 5);
Real-World Examples
E-commerce Product Catalog
// Product field group with variations
acf_add_local_field_group([
'key' => 'group_product_details',
'title' => 'Product Details',
'fields' => [
[
'key' => 'field_product_sku',
'label' => 'SKU',
'name' => 'sku',
'type' => 'text',
'required' => true,
'show_in_graphql' => true
],
[
'key' => 'field_product_gallery',
'label' => 'Product Gallery',
'name' => 'gallery',
'type' => 'gallery',
'return_format' => 'array',
'show_in_graphql' => true
],
[
'key' => 'field_product_variations',
'label' => 'Variations',
'name' => 'variations',
'type' => 'repeater',
'show_in_graphql' => true,
'sub_fields' => [
[
'key' => 'field_variation_name',
'label' => 'Variation Name',
'name' => 'name',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_variation_price',
'label' => 'Price',
'name' => 'price',
'type' => 'number',
'min' => 0,
'step' => 0.01,
'show_in_graphql' => true
],
[
'key' => 'field_variation_stock',
'label' => 'Stock Quantity',
'name' => 'stock',
'type' => 'number',
'min' => 0,
'show_in_graphql' => true
],
[
'key' => 'field_variation_attributes',
'label' => 'Attributes',
'name' => 'attributes',
'type' => 'group',
'show_in_graphql' => true,
'sub_fields' => [
[
'key' => 'field_attr_color',
'label' => 'Color',
'name' => 'color',
'type' => 'color_picker',
'show_in_graphql' => true
],
[
'key' => 'field_attr_size',
'label' => 'Size',
'name' => 'size',
'type' => 'select',
'choices' => [
'xs' => 'XS',
's' => 'S',
'm' => 'M',
'l' => 'L',
'xl' => 'XL'
],
'show_in_graphql' => true
]
]
]
]
]
],
'location' => [
[
[
'param' => 'post_type',
'operator' => '==',
'value' => 'product'
]
]
],
'show_in_graphql' => true,
'graphql_field_name' => 'productDetails'
]);
Portfolio with Case Studies
// Case study fields with dynamic sections
acf_add_local_field_group([
'key' => 'group_case_study',
'title' => 'Case Study Details',
'fields' => [
[
'key' => 'field_client_info',
'label' => 'Client Information',
'name' => 'client_info',
'type' => 'group',
'show_in_graphql' => true,
'sub_fields' => [
[
'key' => 'field_client_name',
'label' => 'Client Name',
'name' => 'name',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_client_logo',
'label' => 'Client Logo',
'name' => 'logo',
'type' => 'image',
'return_format' => 'array',
'show_in_graphql' => true
],
[
'key' => 'field_client_industry',
'label' => 'Industry',
'name' => 'industry',
'type' => 'taxonomy',
'taxonomy' => 'industry',
'return_format' => 'object',
'show_in_graphql' => true
]
]
],
[
'key' => 'field_project_metrics',
'label' => 'Project Metrics',
'name' => 'metrics',
'type' => 'repeater',
'show_in_graphql' => true,
'sub_fields' => [
[
'key' => 'field_metric_label',
'label' => 'Metric Label',
'name' => 'label',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_metric_value',
'label' => 'Value',
'name' => 'value',
'type' => 'text',
'show_in_graphql' => true
],
[
'key' => 'field_metric_icon',
'label' => 'Icon',
'name' => 'icon',
'type' => 'select',
'choices' => [
'growth' => 'Growth',
'revenue' => 'Revenue',
'users' => 'Users',
'performance' => 'Performance'
],
'show_in_graphql' => true
]
]
]
],
'location' => [
[
[
'param' => 'post_type',
'operator' => '==',
'value' => 'case_study'
]
]
],
'show_in_graphql' => true,
'graphql_field_name' => 'caseStudyDetails'
]);
GraphQL Queries for Real-World Examples
# E-commerce product query
query GetProductWithVariations($id: ID!) {
product(id: $id) {
id
title
productDetails {
sku
gallery {
id
sourceUrl
altText
}
variations {
name
price
stock
attributes {
color
size
}
}
}
}
}
# Case study query
query GetCaseStudy($slug: String!) {
caseStudyBy(slug: $slug) {
id
title
content
caseStudyDetails {
clientInfo {
name
logo {
sourceUrl
altText
}
industry {
name
slug
}
}
metrics {
label
value
icon
}
}
}
}
Best Practices
Field Naming Conventions
// Consistent naming for GraphQL
$naming_conventions = [
'field_key' => 'field_{group}_{name}', // field_product_price
'graphql_name' => 'camelCase', // productPrice
'group_key' => 'group_{post_type}_{purpose}', // group_product_details
'layout_key' => 'layout_{name}', // layout_hero_section
];
Security Considerations
// Restrict sensitive fields from GraphQL
add_filter('graphql_acf_field_config', function($field_config, $acf_field) {
// Hide sensitive fields
$sensitive_fields = ['api_key', 'secret_token', 'private_notes'];
if (in_array($acf_field['name'], $sensitive_fields)) {
$field_config['show_in_graphql'] = false;
}
// Require authentication for certain fields
if ($acf_field['name'] === 'internal_data') {
$field_config['resolve'] = function($root, $args, $context) use ($acf_field) {
if (!$context->viewer->ID) {
return null; // Return null for non-authenticated users
}
return get_field($acf_field['name'], $root->ID);
};
}
return $field_config;
}, 10, 2);
Testing ACF GraphQL Integration
// Jest test example
describe('ACF GraphQL Integration', () => {
it('should return product variations', async () => {
const query = `
query GetProduct($id: ID!) {
product(id: $id) {
productDetails {
variations {
name
price
}
}
}
}
`;
const result = await graphql(query, { id: 'product-123' });
expect(result.data.product.productDetails.variations).toHaveLength(3);
expect(result.data.product.productDetails.variations[0]).toHaveProperty('price');
});
});
Migration Strategy
// Migrate existing ACF fields to GraphQL
function migrate_acf_to_graphql() {
$field_groups = acf_get_field_groups();
foreach ($field_groups as $group) {
// Update field group
$group['show_in_graphql'] = true;
$group['graphql_field_name'] = lcfirst(str_replace(' ', '', $group['title']));
// Update fields
$fields = acf_get_fields($group['key']);
foreach ($fields as $field) {
$field['show_in_graphql'] = true;
$field['graphql_field_name'] = $field['name'];
acf_update_field($field);
}
acf_update_field_group($group);
}
}
Conclusion
Integrating ACF with WPGraphQL opens up powerful possibilities for headless WordPress development. By properly configuring field groups, implementing custom resolvers, and following performance best practices, you can build sophisticated content structures that are easily queryable through GraphQL.
Key takeaways: - Always enable GraphQL support when creating ACF fields - Use proper field types and return formats for optimal GraphQL compatibility - Implement custom resolvers for computed or complex data - Optimize performance with caching and batch loading - Follow security best practices to protect sensitive data - Test your GraphQL queries thoroughly
The combination of ACF's flexibility and GraphQL's query efficiency makes this integration essential for modern headless WordPress projects.
Explore more headless WordPress techniques in our comprehensive Headless WordPress Guide.