Skip to content

Populating Options

Instead of supplying different field types like Posts, Users or Terms, Blockstudio allows for a modular way of populating data right from the block.json. This feature works for select, radio, checkbox, color and gradient field types.

Data can be populated in four ways:

  • Query – Return results from a post, user or term query
  • Fetch – Return results from an external source
  • Function – Return results from a custom function
  • Custom – Return results from a custom dataset

Query

When choosing query mode, Posts, Users or Terms can be populated.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

Available query types use these WordPress functions internally:

Query Function
posts get_posts
users get_users
terms get_terms

Arguments

Custom arguments can be passed using the arguments attribute:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Return Format

By default, Blockstudio returns:

Query Value Label
posts post object post_title
users user object display_name
terms term object name

Customize the response with returnFormat:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Fetch Mode

Enable dynamic searching with the fetch option:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

This enables stylisedUi and fetches the first 20 posts initially. Typing in the select field searches posts using the s argument.

Function

Use a custom function to populate options:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Arguments

Pass arguments as an array (uses call_user_func_array internally):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Return Format

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Mixing Options

Combine static options with populated data:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

The position option (before or after) controls where populated options appear relative to static options.

Warning

Mixing options and populate data is not supported when using fetch mode.

Custom Data

Create reusable datasets with the blockstudio/blocks/attributes/populate filter. The filter receives a single argument, an array of all custom datasets keyed by name. Add your dataset under a key and return the array:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

Then reference the key in your block:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

External Data

Fetch data from an external source:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

The search term is appended to urlSearch.

Dynamic Arguments

Populate arguments can reference other block attributes using {attributes.*} syntax. When the referenced attribute changes, the field re-fetches its options automatically.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

This works with all populate types (query, function, custom). Any value in the populate configuration containing {attributes.*} is resolved client-side with the current attribute value before the query runs.

References use the editor’s stored values. For a select option, use {attributes.post_type.value} for its value or {attributes.post_type.label} for its label; returnFormat controls the template value, not this stored editor shape.

Nested arguments are resolved without serializing them into a template string. An argument consisting of one placeholder keeps its referenced type, including numbers, booleans, arrays, and objects. A placeholder embedded in other text produces a string. Missing references are left unchanged, and quoted or multiline values are sent intact. Function callbacks keep their positional argument lists. The editor adds WordPress search arguments only to query populates, not to function calls.

Rendering Dependent Selections

Dependent options are not loaded when the block is registered, because each block instance can have different arguments. Rendering uses the saved selection instead of discarding it against an empty option list. The populate callback is not executed again on the frontend.

The field’s returnFormat still applies:

returnFormat Single select Multiple select
value (default) The saved value, for example "a" An array of saved values, for example ["a", "b"]
label The saved label An array of saved labels
both The saved {value, label} option An array of saved options

For query-populated selections, values still resolve to the corresponding WordPress post, user, or term object unless populate.returnFormat.value is "id". Labels come from the saved selection. If an imported selection has no label, its value is used as the label. A matching static option declared in options takes precedence over the saved option, so its current label applies.

Empty selections remain false (or the field’s configured fallback). This does not change validation of ordinary static options: a saved value that is no longer in a static option list still returns false.

Dynamic selects also preserve default and fallback selections while their options are deferred. Use a scalar value, a {value, label} option, or an array of either for a multiple select. A scalar uses its value as the label unless it matches a declared static option. An option object preserves its supplied label; a matching static option takes precedence. No populate callback runs on the server to look up these defaults.