bricks_set_query_loop

Phase 4AdvancedComplexity: 8/10
Configure a query loop on an element (post, term, user, ACF)

Overview

Configure a query loop on a Bricks element to repeat it for each result in a WordPress query. Supports four object types: post (WP_Query for posts/pages/CPTs), term (WP_Term_Query for categories/tags), user (WP_User_Query), and api (external REST API endpoints).

This is the primary tool for displaying dynamic content in Bricks — blog grids, product listings, team directories, taxonomy archives, and external API data. The element with hasLoop becomes a template that repeats for each query result.

CRITICAL: Never put hasLoop on a grid container. Use a 2-level structure: parent grid div (layout only) containing a child div (hasLoop) that gets repeated as grid items.

Key Features

Four Object Types
Query posts (WP_Query), terms (WP_Term_Query), users (WP_User_Query), or external APIs — all through a single unified interface.
Advanced Filtering
Supports tax_query for taxonomy filtering, meta_query for custom field filtering, and combined queries with AND/OR relations.
API Integration
Connect to external REST APIs with authentication (API key, Bearer, Basic), custom headers, pagination, and response path extraction.
Query Editor
Optional PHP code editor mode for advanced custom query arguments that go beyond the standard parameter interface.

When to Use

Displaying a grid of blog posts, portfolio items, or any custom post type
Creating taxonomy term listings (categories, tags, product categories)
Building user directories or team member grids from WordPress users
Fetching and displaying data from external REST APIs
Setting up archive-style layouts with dynamic content
Prerequisites
An existing page with at least one container/div element to attach the query to
For post queries: the target post type must exist (built-in or registered via bricks_register_post_type)
For term queries: the taxonomy must exist
For API queries: a publicly accessible REST API endpoint

When NOT to Use

Displaying static content that does not come from a query — use bricks_add_section instead
Putting hasLoop directly on a grid container — this creates N separate grids instead of N items in one grid
You need the same query on multiple pages — create a global query with bricks_create_global_query first

Parameters

16 Total Parameters2 Required14 Optional
page_idnumberREQUIRED
Page (post) ID containing the target element.
element_idstringREQUIRED
Element ID to apply the query loop on. Must be a container, block, or div element. CRITICAL: use the child div inside a grid, not the grid itself.
query.objectTypestringoptional
Query object type determining which WordPress query class is used.
Default: post Values: post, term, user, api
query.post_typestring | string[]optional
[post] Post type(s) to query. Accepts a single slug or array of slugs.
Default: post
query.posts_per_pagenumberoptional
[post] Number of posts to return per page.
Default: 6
query.orderbystringoptional
[post/term/user] Field to order results by. Post: date, title, menu_order, rand, modified, comment_count, meta_value, meta_value_num, ID. Term: name, slug, term_id, count. User: ID, login, display_name, registered, post_count.
Default: date
query.orderstringoptional
Sort direction for results.
Default: DESC Values: ASC, DESC
query.tax_queryarrayoptional
[post] Array of taxonomy filter objects. Each with taxonomy (slug), terms (IDs or slugs), field (term_id or slug), and operator (IN, NOT IN, AND).
query.meta_queryarrayoptional
[post/term/user] Array of meta field filter objects. Each with key, value, compare (=, !=, >, <, LIKE, IN, EXISTS, etc.), and optional type (CHAR, NUMERIC, DATE).
query.exclude_current_postbooleanoptional
[post] Automatically exclude the current post being viewed. Useful for related posts sections.
query.taxonomystring | string[]optional
[term] Taxonomy name(s) to query terms from.
query.hide_emptybooleanoptional
[term] Exclude terms with no associated posts.
Default: true
query.rolestring | string[]optional
[user] Filter users by role(s).
query.api_urlstringoptional
[api] Full API endpoint URL for external data source.
query.response_pathstringoptional
[api] Dot-notation path to the data array in the API response (e.g., "data.items").
content_areastringoptional
Content area where the element resides.
Default: content Values: content, header, footer

Code Examples


Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Correct 2-level grid + loop pattern

The correct way to display query results in a grid. The grid parent has NO hasLoop; the child div inside it gets the query loop. This creates one grid with N items instead of N separate grids.

JSON
// Step 1: Add section with 2-level structure
bricks_add_section({
  page_id: 123,
  section: {
    type: "section",
    children: [{
      type: "container",
      children: [{
        type: "div",
        ref: "posts-grid",
        settings: {
          _display: "grid",
          _gridTemplateColumns: "1fr 1fr 1fr",
          "_gridTemplateColumns:tablet_portrait": "1fr 1fr",
          "_gridTemplateColumns:mobile_portrait": "1fr",
          _gap: "30"
        },
        children: [{
          type: "div",
          ref: "loop-item",
          settings: {
            _display: "flex",
            _direction: "column"
          },
          children: [
            { type: "heading", ref: "card-title", settings: { tag: "h3", text: "Title" }, globalClasses: ["heading-card"] },
            { type: "text-basic", ref: "card-desc", settings: { text: "Excerpt" }, globalClasses: ["text-body"] }
          ]
        }]
      }]
    }]
  }
});

// Step 2: Set query on the CHILD div, NOT the grid parent
bricks_set_query_loop({
  page_id: 123,
  element_id: "<loop-item-id>",
  query: {
    objectType: "post",
    post_type: "portfolio",
    posts_per_page: 6,
    orderby: "date",
    order: "DESC"
  }
});

// Step 3: Set dynamic data on card elements
bricks_set_dynamic_data({ page_id: 123, element_id: "<card-title-id>", setting_key: "text", tag: "bricks_set_query_loop" });
bricks_set_dynamic_data({ page_id: 123, element_id: "<card-desc-id>", setting_key: "text", tag: "Configure a query loop on an element (post, term, user, ACF)" });

Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Query with taxonomy and meta filters

Filter posts by category and a custom meta field, ordered by a numeric meta value.

JSON
bricks_set_query_loop({
  page_id: 45,
  element_id: "abc123",
  query: {
    objectType: "post",
    post_type: "product",
    posts_per_page: 12,
    orderby: "meta_value_num",
    meta_key: "price",
    order: "ASC",
    tax_query: [
      { taxonomy: "product_cat", terms: [5, 12], field: "term_id", operator: "IN" }
    ],
    meta_query: [
      { key: "in_stock", value: "1", compare: "=" }
    ]
  }
});

Common Mistakes


Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
This is the #4 quality issue. When hasLoop is on a grid element, Bricks creates N separate grid containers (each with 1 item) instead of 1 grid with N items. Always use a 2-level structure: parent div with _display: "grid" (no hasLoop) containing a child div with hasLoop that repeats as grid items.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49
After configuring the query loop, you must use bricks_set_dynamic_data on each child element to connect them to query data (e.g., bricks_set_query_loop, Configure a query loop on an element (post, term, user, ACF), {featured_image_url}). Without this, every loop iteration shows the same static placeholder text.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49