Skip to main content

Meta Box in Custom Queries

No GraphQL Required for Meta Box Usage

Most Meta Box 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 Meta Box integration →

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

When to Use Custom Meta Box GraphQL Queries​

Built-in Meta Box integration covers most use cases. Use custom GraphQL queries when you need:

  • Advanced filtering - Use Meta Box fields in query arguments
  • Complex relationships - Complex Meta Box connections
  • Custom formatting - Transform field values with expressions
  • Performance control - Optimize expensive queries with @private
  • Cross-context access - Meta Box fields from different post types together

Meta Box Field Access Methods​

Understanding the difference between metabox_value() and specialized Meta Box methods:

Builderius provides two approaches for accessing Meta Box fields - simple value retrieval and advanced object access. The choice depends on how much control you need over the returned data.

Simple vs Advanced Methods​

Simple Method (metabox_value): Returns the field value as configured in Meta Box settings - could be just an ID, URL, or basic data depending on field configuration.

Advanced Methods (metabox_post_value, metabox_user_value, etc.): Always return the full WordPress object regardless of Meta Box field settings, giving you complete access to all object properties and related data.

Post Object Example​

Simple Method​

GraphQL with metabox_value():

{
  post {
    # Returns whatever the Meta Box field format is set to
    featured_article: metabox_value(field_id: "featured_article")
  }
}

Advanced Method​

GraphQL with metabox_post_value():

{
  post {
    # Select only the fields you need
    featured_article: metabox_post_value(field_id: "featured_article") {
      post_title
      permalink
      featured_image {
        file_url
        alt_text
      }
      # Access Meta Box fields on the related post
      reading_time: metabox_value(field_id: "reading_time")
    }
  }
}

The key difference: The advanced method requires you to define subfields and 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. A [[custom.featured_article.post_title]] will be added to your element.

Meta Box Syntax Rule​

Important:

Meta Box field access depends on context:

Settings Pages (Root Level) - REQUIRES option_name:

metabox_value(field_id: "contact_email", option_name: "site_settings")

Posts/Pages/Terms/Users - NO option_name:

metabox_value(field_id: "contact_email")

This is the most common source of errors when working with Meta Box in GraphQL.

Querying Meta Box Fields​

metabox_value(field_id: "field_name") - Returns the field value

Applies to all basic field types:

  • Text, Textarea, Number, Email, URL
  • Select, Radio, Checkbox
  • Date, Datetime
  • Color, Switch (boolean)
  • Image/File fields (returns URL or object based on settings)
{
  post {
    # Text and content fields
    subtitle: metabox_value(field_id: "subtitle")
    price: metabox_value(field_id: "price") 
    featured: metabox_value(field_id: "featured")
    event_date: metabox_value(field_id: "event_date")
    brand_color: metabox_value(field_id: "brand_color")
    
    # Image field (with size parameter)
    hero_image_url: metabox_value(field_id: "hero_image", args: "size=medium")
    
    # Transform values
    formatted_price: expression_result(
      expression: "'$' . price"
    )
    
    formatted_date: expression_result(
      expression: "date('F j, Y', strtotime(event_date))"
    )
  }
}

Filtering with Meta Box Fields​

Use Meta Box 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_id"
      value: "field_value"
      compare: "="
    }
  ]
}

Examples:

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

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

# Boolean field (Meta Box switch)
{
  key: "featured"
  value: 1
  compare: "="
  type: "NUMERIC"
}

Queries With Meta Box Filtering​

Simple field value filtering:

{
  # Featured articles
  featured_articles: posts_query(
    arguments: {
      post_type: "article"
      meta_query: {
        array: [
          {
            key: "featured"
            value: 1
            compare: "="
            type: "NUMERIC"
          }
        ]
      }
    }
  ) {
    posts {
      post_title
      featured: metabox_value(field_id: "featured")
    }
  }

Query Meta Box Based on Different Contexts​

Meta Box fields must be accessed from within their respective WordPress objects, with special syntax for settings pages.

Current Post:

{
  post {
    post_title
    subtitle: metabox_value(field_id: "subtitle")
    event_date: metabox_value(field_id: "event_date")
    featured: metabox_value(field_id: "featured")
  }
}

Specific Post:

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

Multiple Posts:

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

Key Context Rules​

Posts: Meta Box fields accessed within post { ... } or posts { ... }
Terms: Meta Box fields accessed within term { ... } or terms { ... }
Users: Meta Box fields accessed within current_user { ... } or users { ... }
Navigation: Meta Box fields accessed within menu items { ... }
Settings: Meta Box fields require option_name parameter at root level

Remember

Settings pages always require option_name, object-level contexts never use option_name.

Advanced: Field Configuration Access​

MetaBox Field Configuration​

Like ACF's acf_field_object(), you might want to access MetaBox field configuration and metadata - information about how fields are set up rather than their data values.

No Built-in MetaBox Field Object Method

Unlike for ACF, we don't provide a MetaBox dedicated metabox_field_object() method in Builderius. However, you can access field configuration using php_function_output Pro Feature to call MetaBox's native PHP functions directly.

Learn more about php_function_output →

Getting Field Configuration​

Access field settings and metadata:

Get Field Configuration

Access individual field settings using MetaBox's API:

{
  # Get field configuration
  contact_field_config: php_function_output(
    function: "rwmb_get_field_settings"
    arguments: ["contact_email"]
  )
  
  # Get field configuration with context
  image_field_config: php_function_output(
    function: "rwmb_get_field_settings" 
    arguments: ["hero_image", {"object_type": "post"}, 123]
  )
}

Use case: Access field type, validation rules, labels, and other configuration to build dynamic interfaces or validate input.

Get All Fields in a Meta Box

Retrieve all fields from a specific meta box:

{
  # Get all fields for current post
  post_metabox_fields: php_function_output(
    function: "rwmb_get_object_fields"
    arguments: ["my_metabox_id", "post"]
  )
  
  # Get all fields for specific object
  contact_page_fields: php_function_output(
    function: "rwmb_get_object_fields" 
    arguments: ["contact_metabox", "post", 456]
  )
}

Use case: Build dynamic forms or iterate through all fields in a meta box programmatically.

Field Validation and Settings

Access field constraints and settings for validation:

{
  # Get upload field constraints
  image_settings: php_function_output(
    function: "rwmb_get_field_settings"
    arguments: ["profile_photo"]
  )
  
  # Get select field choices
  dropdown_settings: php_function_output(
    function: "rwmb_get_field_settings"
    arguments: ["product_category"]
  )
}

Use case: Display field requirements, show available options for select fields, or validate user input based on field configuration.

Common MetaBox API Functions​

Available functions for php_function_output:

FunctionPurposeArguments
rwmb_get_field_settingsGet field configurationfield_id, args, object_id
rwmb_get_object_fieldsGet all fields for objectobject_type, object_id
rwmb_get_registryAccess field registry'field'

Field Value vs Field Configuration​

  • metabox_value(field_id: "field_name") → The actual data (what users entered)
  • php_function_output(function: "rwmb_get_field_settings", arguments: ["field_name"]) → The configuration (how the field is set up)

Use MetaBox's PHP functions through php_function_output when you need field configuration data for building dynamic interfaces or validation logic.