ACF Local JSON Builder

Generate complete ACF (Advanced Custom Fields) Local JSON configurations from images, designs, or HTML structures for WordPress development.

Core Workflow

• Analyze Input: Examine the provided image, design, or HTML structure

• Identify Components: Detect repeating patterns, content sections, and field relationships

• Map Field Types: Determine appropriate ACF field types for each component

• Generate JSON: Create the complete Local JSON configuration

• Validate Structure: Ensure proper nesting, keys, and field relationships

Field Type Detection Guidelines

From Visual Analysis

• Text inputs/headings → text , textarea , or wysiwyg

• Images → image (consider gallery for multiple)

• Repeating cards/sections → repeater or flexible_content

• Toggle states → true_false or button_group

• Dropdowns/select boxes → select or radio

• Date displays → date_picker or date_time_picker

• Links/buttons → link or url

• Color variations → color_picker

• File downloads → file

• Numbered lists → number or range

• Tab interfaces → tab field type

• Accordions → flexible_content with layouts

From HTML Structure

<!-- Text Field --> <h1>, <h2>, <p> → text/textarea/wysiwyg

<!-- Image Field --> <img> → image field <picture>, <source> → image with return format 'array'

<!-- Repeater Pattern --> <div class="card"> (múltiples) → repeater <ul><li> (dinámicos) → repeater

<!-- Flexible Content Pattern --> Secciones variadas (hero, features, cta) → flexible_content

<!-- Link Field --> <a href=""> → link field

<!-- True/False --> <input type="checkbox"> → true_false

JSON Structure Template

Every ACF Local JSON file follows this structure:

{ "key": "group_unique_identifier", "title": "Field Group Name", "fields": [...], "location": [...], "menu_order": 0, "position": "normal", "style": "default", "label_placement": "top", "instruction_placement": "label", "hide_on_screen": "", "active": true, "description": "" }

Field Structure Patterns

Basic Field

{ "key": "field_unique_key", "label": "Field Label", "name": "field_name", "type": "text", "instructions": "", "required": 0, "conditional_logic": 0, "wrapper": { "width": "", "class": "", "id": "" }, "default_value": "", "placeholder": "", "prepend": "", "append": "", "maxlength": "" }

Repeater Field

{ "key": "field_repeater_key", "label": "Items", "name": "items", "type": "repeater", "instructions": "", "required": 0, "layout": "block", "button_label": "Add Item", "min": 0, "max": 0, "sub_fields": [ { "key": "field_subfield_key", "label": "Title", "name": "title", "type": "text", "parent": "field_repeater_key" } ] }

Flexible Content

{ "key": "field_flexible_key", "label": "Page Builder", "name": "page_builder", "type": "flexible_content", "instructions": "", "button_label": "Add Section", "min": "", "max": "", "layouts": { "layout_hero": { "key": "layout_hero_key", "name": "hero", "label": "Hero Section", "display": "block", "sub_fields": [...] }, "layout_features": { "key": "layout_features_key", "name": "features", "label": "Features Section", "display": "block", "sub_fields": [...] } } }

Image Field

{ "key": "field_image_key", "label": "Image", "name": "image", "type": "image", "return_format": "array", "preview_size": "medium", "library": "all", "min_width": "", "min_height": "", "min_size": "", "max_width": "", "max_height": "", "max_size": "", "mime_types": "" }

Key Generation Rules

Group Keys: group_

• descriptive_snake_case + random_hash

• Example: group_homepage_hero_5f8a2b

Field Keys: field_

• descriptive_snake_case + random_hash

• Example: field_hero_title_9c3d1e

Layout Keys: layout_

• layout_name + random_hash

• Example: layout_hero_section_4b7e9a

Uniqueness: Every key must be globally unique across all ACF installations

Location Rules

Common location patterns:

"location": [ [ { "param": "post_type", "operator": "==", "value": "page" } ] ]

"location": [ [ { "param": "page_template", "operator": "==", "value": "template-homepage.php" } ] ]

"location": [ [ { "param": "post_type", "operator": "==", "value": "post" }, { "param": "post_category", "operator": "==", "value": "category:news" } ] ]

Best Practices

• Semantic Naming: Use clear, descriptive names that reflect content purpose

• Proper Nesting: Maintain correct parent-child relationships in repeaters/flex

• Return Formats: Choose appropriate return formats (ID, array, url for images)

• Instructions: Add helpful instructions for content editors

• Defaults: Set sensible default values where appropriate

• Validation: Include min/max constraints where relevant

• Layout Types: Use block , table , or row layouts appropriately

• Clone Fields: Reference the clone fields documentation for reusable field sets

Output Format

Generate the complete JSON file ready to save as:

acf-json/group_[name].json

The file should be valid JSON and immediately usable in WordPress ACF Pro's Local JSON feature.

Advanced Features

For complex patterns like:

• Clone fields: See references/clone-fields.md

• Bidirectional relationships: See references/relationships.md

• Custom field types: See references/custom-types.md

• Conditional logic: See references/conditional-logic.md

Example Workflow

User provides: Screenshot of a hero section with title, subtitle, CTA button, and background image

Analysis:

• Hero section = Field Group

• Title = text field

• Subtitle = textarea field

• CTA = link field (text + URL)

• Background = image field

Output: Complete JSON with all fields properly structured and nested