Skip to main content

ACF in Custom Queries

GraphQL is Not Required for ACF Usage

ACF fields work automatically in Builderius without writing any GraphQL code. Fields appear in the Dynamic Data dropdown and can be added to any element with a click. Learn about built-in ACF integration →

This article provides guidelines for when you need to use ACF within your custom queries Pro Feature, or when you need specific control not aviailble out of the box.

When to Use Custom ACF GraphQL Queries​

Built-in ACF integration covers many use cases. Use custom GraphQL queries when you need:

  • Filtering - Use ACF fields in query arguments
  • Complex relationships - Complex ACF connections
  • Custom formatting - Transform field values with expressions
  • Performance control - Optimize expensive queries to get only the data you need
  • Cross-context access - ACF fields from different post types together

ACF Field Access Methods​

Understanding the difference between acf_value() and other ACF methods:

Builderius provides two approaches for accessing ACF fields - simple value retrieval and advanced object access. The choice depends on your needs when it comes to what data you need and how much control you need.

Simple vs Other Methods​

Simple Method (acf_value): Returns whatever format the ACF field is configured to return (with some exceptions) - could be just an ID, URL, or basic object depending on field settings. It is simple to use, but offers less control over what you can retrieve and how.

Advanced Methods (acf_post_object_value, acf_user_value, etc.) Pro Feature: These methods require a couple more steps but they come with a lot of benefits. You get way more control. You can pick and choose what data you can retrieve and how. You get — complete control.

Post Object Example​

Simple Method​

GraphQL with acf_value():

{
  post {
    # Returns whatever the ACF field return format is set to
    featured_article: acf_value(name: "featured_article")
  }
}

Advanced Method​

GraphQL with acf_post_object_value():

{
  post {
    # Select only the fields you need
    featured_article: acf_post_object_value(name: "featured_article") {
      post_title
      permalink
      featured_image {
        file_url
        alt_text
      }
      # Access ACF fields on the related post
      reading_time: acf_value(name: "reading_time")
    }
  }
}

The key difference: The acf_post_object_value requires you to define at least one subfield. In the case of Post Object field, these can be any field attatched to a post object; native ones like post_title, post_excerpt etc. or other acf fields tieh a location set to post.

With out autocomplete it's easy to add these fields, and the benefits are important. The advanced method gives you control over which data you retrieve, making queries more efficient by requesting only what you need, rather than getting the entire object dump.

How do you later access these subfields? Use the Dynamic Data dropdown, click the post object field that appears, and select the subfield when the object expands in the dropdown. A [[custom.post.featured_article.post_title]] will be added to your element and it will render in the canvas.

Querying ACF Fields​

acf_value(name: "field_name") - Returns the field value

Applies to all basic field types:

  • Text, Textarea, Number, Email, URL, Password
  • Select, Radio, Checkbox, Button Group
  • True/False (boolean)
  • Date Picker, Time Picker, Date Time Picker
  • Color Picker, Range, WYSIWYG Editor
  • Image/File fields (when return format = URL or ID)
  • Single selections from relationship fields
{
  post {
    # Text and content fields
    subtitle: acf_value(name: "subtitle")
    price: acf_value(name: "price") 
    featured: acf_value(name: "featured")
    event_date: acf_value(name: "event_date")
    brand_color: acf_value(name: "brand_color")
    
    # Image field (URL format)
    hero_image_url: acf_value(name: "hero_image")
    
    # Transform values
    formatted_price: expression_result(
      expression: "'$' . price"
    )
    
    formatted_date: expression_result(
      expression: "date('F j, Y', strtotime(event_date))"
    )
  }
}

Filtering with ACF Fields​

Use ACF fields in query arguments to filter posts, users, and terms based on custom field values.

Meta Query Syntax Reference​

Basic single condition syntax:

meta_query: {
  array: [
    {
      key: "field_name"
      value: "field_value"
      compare: "="
    }
  ]
}

Examples:

# Text field
{
  key: "status"
  value: "published"
  compare: "="
}

# Number field
{
  key: "rating"
  value: 5
  compare: "="
  type: "NUMERIC"
}

# Boolean field
{
  key: "featured"
  value: true
  compare: "="
  type: "BOOLEAN"
}

Use ACF filtering to find posts with specific field values, creating dynamic content based on custom field criteria.

Queries With ACF Filtering​

Simple field value filtering:

{
  # Featured articles
  featured_articles: posts_query(
    arguments: {
      post_type: "article"
      meta_query: {
        array: [
          {
            key: "featured"
            value: true
            compare: "="
            type: "BOOLEAN"
          }
        ]
      }
    }
  ) {
    posts {
      post_title
      featured: acf_value(name: "featured")
    }
  }

Query ACF Based on Different Contexts​

Current Post:

{
  post {
    post_title
    subtitle: acf_value(name: "subtitle")
    event_date: acf_value(name: "event_date")
    featured: acf_value(name: "featured")
  }
}

Specific Post:

{
  about_page: post(identifier: "slug", value: "about") {
    post_title
    company_name: acf_value(name: "company_name")
    founding_year: acf_value(name: "founded")
  }
}

Posts Loop:

{
  articles: posts_query(
    arguments: {
      post_type: "article"
      posts_per_page: 5
    }
  ) {
    posts {
      post_title
      reading_time: acf_value(name: "reading_time")
      author_bio: acf_value(name: "author_bio")
    }
  }
}

Key Context Rules​

Posts: ACF fields accessed within post { ... } or posts { ... }
Terms: ACF fields accessed within term { ... } or terms { ... }
Users: ACF fields accessed within current_user { ... } or users { ... }
Navigation: ACF fields accessed within menu items { ... }
Options: ACF fields accessed directly at root level (no wrapper needed)

Advanced Field Metadata Access​

ACF Field Configuration​

Beyond accessing field values, you can also query the field configuration and metadata using acf_field_object(). This returns information about how the field is set up rather than the data it contains.

Here is an example of the acf_field_object() for acf image field​

"acf_field_object": {
    "ID": 148,
    "key": "field_692155ef32f1e",
    "label": "img",
    "name": "img",
    "aria-label": "",
    "prefix": "acf",
    "type": "image",
    "value": null,
    "menu_order": 2,
    "instructions": "",
    "required": 0,
    "id": "",
    "class": "",
    "conditional_logic": 0,
    "parent": 131,
    "wrapper": {
      "width": "",
      "class": "",
      "id": ""
    },
    "return_format": "array",
    "library": "all",
    "min_width": "",
    "min_height": "",
    "min_size": "",
    "max_width": "",
    "max_height": "",
    "max_size": "",
    "mime_types": "",
    "allow_in_bindings": 0,
    "preview_size": "medium",
    "_name": "img",
    "_valid": 1
  }

When to use acf_field_object():

  • Build dynamic interfaces that adapt based on field configuration
  • Create conditional content based on field types and settings
  • Access field choices for select/radio/checkbox fields
  • Validate data against field constraints
  • Display field labels and instructions dynamically

The key difference: acf_value() gives you the data, acf_field_object() gives you the schema.

Get Field Choices and Options

Access the available choices for select, radio, and checkbox fields:

{
  color_field_config: acf_field_object(name: "product_color")
  size_field_config: acf_field_object(name: "product_size")
}

Returns field configuration with choices:

{
  "color_field_config": {
    "type": "select",
    "label": "Product Color",
    "choices": {
      "red": "Red",
      "blue": "Blue", 
      "green": "Green"
    }
  }
}

Use case: Build dynamic dropdowns, display all available options, or show human-readable labels for selected values.

Field Labels and Instructions

Get field metadata for display purposes:

{
  image_field_info: acf_field_object(name: "hero_image")
}

Returns field configuration:

{
  "image_field_info": {
    "type": "image",
    "label": "Hero Image",
    "instructions": "Upload a high-resolution image for the hero section",
    "required": 1
  }
}

Use case: Show field labels in forms, display help text, or add required field indicators.

Conditional Content Based on Field Types

Use field type information for conditional display in Builderius conditions tool:

{
  dynamic_field_config: acf_field_object(name: "content_block")
  dynamic_field_value: acf_value(name: "content_block")
}

Use case: In Builderius conditions, check if dynamic_field_config.type equals "image" to show image components, "wysiwyg" to show rich text, or "select" to display choice-based content. This allows one template to handle multiple field types dynamically.

Validation Rules and Constraints

Access field constraints for validation or display logic:

{
  upload_constraints: acf_field_object(name: "profile_photo")
}

Returns validation rules:

{
  "upload_constraints": {
    "type": "image",
    "required": 1,
    "min_width": "300",
    "max_width": "1200", 
    "mime_types": "jpg,jpeg,png",
    "return_format": "array"
  }
}

Use case: Display upload requirements to users, validate file dimensions, or determine how to process the field value based on return_format.

Dynamic Form Building

Query multiple field configurations to build forms dynamically:

{
  contact_form_fields: {
    name_field: acf_field_object(name: "contact_name")
    email_field: acf_field_object(name: "contact_email") 
    country_field: acf_field_object(name: "contact_country")
    message_field: acf_field_object(name: "contact_message")
  }
}

Use case: Build contact forms or user input interfaces that adapt based on field configurations, showing appropriate input types and validation rules for each field.

Layout and Styling Configuration

Access wrapper attributes set in ACF field configuration (available on any field type):

{
  # Any field type can have wrapper settings
  name_field_config: acf_field_object(name: "contact_name")
  image_field_config: acf_field_object(name: "hero_image")
}

Returns wrapper configuration from ACF admin settings:

{
  "name_field_config": {
    "type": "text",
    "wrapper": {
      "width": "50",
      "class": "required-field",
      "id": "contact-name"
    }
  }
}

Use case: Apply the same CSS classes, widths, and IDs that were configured in the ACF admin to your frontend elements for consistent styling.

Conditional Logic Rules

Access ACF conditional logic to replicate admin behavior on frontend:

{
  membership_value: acf_value(name: "membership_type")
  company_field_config: acf_field_object(name: "company_size")
  premium_field_config: acf_field_object(name: "premium_features")
}

Returns conditional logic rules:

{
  "membership_value": "premium",
  "company_field_config": {
    "conditional_logic": [
      [
        {
          "field": "membership_type",
          "operator": "==",
          "value": "enterprise"
        }
      ]
    ]
  },
  "premium_field_config": {
    "conditional_logic": [
      [
        {
          "field": "membership_type", 
          "operator": "==",
          "value": "premium"
        }
      ]
    ]
  }
}

Practical use case:

  • In Builderius conditions, show company size field only when [[custom.membership_value]] equals "enterprise"
  • Display premium features section when [[custom.membership_value]] equals "premium"
  • Build dynamic forms where field visibility matches exactly what users see in WordPress admin
  • Create conditional content blocks that appear/disappear based on user selections, keeping frontend behavior synchronized with backend field logic

Field Object vs Field Value Summary​

  • acf_value(name: "field_name") → The actual data (what users entered)
  • acf_field_object(name: "field_name") → The configuration (how the field is set up)

Use acf_field_object() when building flexible, dynamic interfaces that need to adapt based on field configuration rather than field values.