The Query Loop builder is available for all layout elements, Accordion, and Slider elements.
It can also be enabled for the Accordion (Nestable), Tabs (Nestable), and Slider (Nestable).
It lets you query your database (according to your query parameters) and renders the query results you want to show inside the loop (dynamic data).
You can query post types, taxonomy terms, and users. Some typical use cases are:
- Posts: Latest posts, related posts (works for any registered & public post type)
- Terms: Post categories & tags, product categories, etc.
- Users: List blog authors, community members, and team members
Creating A Custom Loop
Add a “Container” element to the canvas. Enable the Use Query Loop to turn your container into a loop item.
Once you’ve enabled the Use Query Loop setting, you’ll see a Query control (loop or infinity icon). This is where you set the parameters according to which the content is retrieved.
This container now serves as your repeater item. All elements inside this container are repeated as many times as the results of the query.
The Query Control
The Query control now supports three different object types: posts, terms and users.
- Posts enable a WP_Query type of query. This is the default query type and should be used when you want to display a loop of posts, pages, media files, or custom post types.
- Terms enable the WP_Term_Query. This should be used when you want to loop through the different terms of a taxonomy. Useful to list all the product categories that contain products.
- Users enable the WP_User_Query. This should be used when you want to loop through a set of site users. Useful to list the blog authors or a list of team members (as long as they are inserted as site users).
The query controls adapt according to the selected query type.
Posts query
Post type: Select one or multiple post types (default: posts)
Order by: Order the results by post ID, author, title, published or modified date, comment count, relevance, menu order, or random (default: published date).
Order: Ascending or Descending (default).
Posts Per Page: The number of posts to show per page (default: WordPress settings → Reading → Blog pages show at most)
Offset: The number of posts to skip.
Ignore Sticky Posts: Turn this on if do not want to move sticky posts to the start of the set.
Disable Query Merge: Turn this on if do not want the query to be auto-merged by Bricks in archive pages, search pages, etc. Usually, you will turn this on for the Query loops in the footer, header, or non-main query. This is the GUI for the bricks/posts/merge_query filter.
Child Of: Set the parent ID to return all its children only. (post_parent in WP_Query)
Include/Exclude: If you want to include or exclude one or multiple posts from the query.
Exclude Current Post: If enabled it will exclude the current post from the loop (useful to build a “related posts” section)
Terms Include/Exclude: Include or Exclude posts that have one or multiple terms.
Taxonomy Query: Add one or multiple taxonomy queries to filter the posts.
Tax Query Relation: Define if the taxonomy queries should be inclusive (OR) or exclusive (AND).
Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.
Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).
Random seed TTL: Duration in minutes for which the random seed exists. Set to prevent duplicate post results (only needed & available when using a random order query loop). Set “0” to turn this feature off.
If you set the TTL to 10 minutes the query result remains the same for the next 10 minutes. This ensures that no duplicate posts are displayed on different pages or when the infinite scroll is active. (@since 1.7.1)
Is main query (Archive): When creating an archive template, choose one of the loops as the main query. This will prevent a 404 error from occurring when visitors navigate to different pages. Turn on to designate the main query. Remember to set the correct query on your pagination element as well.
However, do not turn on this option for multiple queries on the same page, as only the first one will be set as the archive main query. (@since 1.8)
Example 1: Latest Posts
In this example, we’ll list the latest four posts (each item shows the featured image, post title, and excerpt) using the Query Loop Builder.
We start by adding a container to the canvas. This container holds our loop and serves as the blueprint for each query item.
Next, we enable the “Use Query Loop” setting to turn our simple container into a query loop.
Inside our container, we add an image element and set it to “Featured Image” using the Dynamic Data dropdown.
In the same container, add another container with a Heading and a Text element.
For the Heading element, we add the {post_title} tag.
For the Text element, we add {post_excerpt} tag.
If you like, you could use the Post Title element or the Post Excerpt element instead.
By default, the query control shows the latest posts, but because we want to restrict the number of posts shown, you need to edit the Query setting and set the Posts Per Page control to 4, to restrict the output to max. four rows.
Media Query
Bricks 1.5 introduces the possibility to query for media files (the attachment post type). In the Posts query type, you’ll now find the Media post type.
After selecting Media in the post type control, you’ll get a new control to define the mime type. By default, Bricks will automatically query for images but you may define other mime types (if more than one, separate them by a comma, e.g. image/jpeg,image/png,image/gif).
To query for the images attached to a post, you may use the Child of control to specify the post ID. To do it dynamically, you may use dynamic data to fetch the current post id: {post_id}.
Example 2: Media Gallery
The media query opens the possibility to build a custom media gallery using the Query Loop builder. To start you would need to add a Container element, insert a Block element inside it, and finally an image element inside of the Block.
In the container, you’ll set the flex-wrap to wrap, and the direction to horizontal (row). In the Block, you’ll need to activate the Query Loop and set the Media post type, and the number of images you’ll want to get (posts per page). In the Block layout, you need to set the width and the height (e.g. 300px).
In the Image, you’ll set the dynamic data as {post_id} – note that the query returns the attachment posts (media files), so the image ID is the post ID. To complete the layout, set the image object-fit to cover, and the height to 300px.
Terms Query
Taxonomies: Select one or multiple taxonomies to query (default: none)
Order by: Order the results by term ID, term name, term parent, count or include list.
Order: Ascending (default) or Descending.
Number: The number of terms to show per page. WordPress default is all but Bricks defaults to the number defined in the WordPress settings → Reading → Blog pages show at most. Use 0 to display all the results.
Offset: The number of terms to skip.
Parent: Parent term ID to retrieve direct-child terms of. Set this to 0 to fetch only the terms that have children. Ex.: Given this structure, entering 55 would get only the Tshirts.
Child of: Term ID to retrieve child terms of. Ex.: Given this structure, entering 55 would get Tshirts and Tees.
Childless: (bool) True to limit results to terms that have no children. This parameter has no effect on non-hierarchical taxonomies. Default false.
Disable Query Merge: Turn this on if do not want the query to be auto-merged by Bricks. (@since 1.7.1)
Terms Include/Exclude: Include or Exclude terms from the query
Show empty: Whether to show terms not assigned to any posts.
Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.
Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).
No Results: Text to be shown when there are no matching results.
Example 3: Product Categories
In this example, we’ll build a dynamic list of product categories (product category image + a link to the category archive).
The example is based on the WooCommerce plugin and the sample products. We’ll need one container to hold the container loop. Inside the container loop, we’ve added a Basic Text element that contains the Dynamic Data {term_name} tag.
After setting the Query to loop through “terms”, and selecting the Taxonomy “Product Categories” you’ll get in the canvas as many containers as the existing categories. Inside the loop, you’ll be able to use several dynamic data tags to fetch the term’s data, such as the term id, the term name, the term archive URL, the term description, and any term meta.
In this example, we set the loop container background image as the product category thumbnail, using the Dynamic Data dropdown and selecting the Product Category Image tag:
We also set the loop container as a link to the product category archive page (using the Term Archive URL dynamic data tag). You’ll need to set the HTML tag to “a (link)”, and the link type to Dynamic Data which will enable the Dynamic Data dropdown:
Users Query
Roles: Select one or multiple user roles to query (default: any)
Order by: Order the results by user ID, name, username, nicename, login, email, registered date, post count, or include list.
Order: Ascending (default) or Descending.
Number: The number of users to show per page. WordPress defaults to all but Bricks defaults to the number defined in the WordPress settings > Reading > Blog pages show at most. Use -1 to display all the results.
Offset: The number of users to skip.
Disable Query Merge: Turn this on if do not want the query to be auto-merged by Bricks. (@since 1.7.1)
Meta Query: Add one or multiple meta queries to filter the posts based on the custom fields.
Relation: Define if the meta queries should be inclusive (OR) or exclusive (AND).
No Results: Text to be shown when there are no matching results.
Example 4: The blog authors
In this example, we want to build a section to list all the blog authors.
The blog authors are website users with the role of author. As in the other examples, we’ve used a container to loop through the users. In that container, we’ve set a query of user type, setting roles to “Author” to pull only the website’s authors.
Inside the loop container, we’ve added an Image and a Basic Text element.
The image we’ve set it to display an ACF Dynamic Data field containing the profile image. In the Basic Text, we’ve used the Dynamic Data {wp_user_display_name} tag.
The Pagination element
The perfect companion to the custom query loop builder. You’ll find the Pagination element under the WordPress group of the elements panel.
Having pagination as a separate element offers you the most flexibility to build any kind of layout.
After adding the Pagination element to the canvas, you’ll need to link this pagination element to one of the elements that run a query. To do so, please select the element in the Related Query control, by editing the Pagination element:
Tip: to make it easier to recognize elements, give descriptive element names to the containers that have a query enabled.
Load more (button)
Besides the infinite scroll, which automatically loads more results as you scroll down the page, you can also give any element (typically the Button) a “Load more” functionality by adding a “Load more” click interaction to it like this:
Query Loop in Accordions & Sliders
The Accordion & Slider elements also allow to pull data dynamically through the Query Loop to feed the element parts.
In the Accordion element, you’ll find a Query Loop control to configure a query. The query results create as many accordion items as the results of the query.
You’ll be able to configure the accordion title, subtitle, and content of the “master” accordion item, and this will be used as a template for the dynamic accordion items:
The same happens in the Slider element. If the Query Loop is enabled, you’ll have access to a Query control and a slide item which will behave as the template for all the slides.
Query Loop Hooks
- bricks/query/run (filter)
- bricks/terms/query_vars (filter)
- bricks/users/query_vars (filter)
- bricks/posts/merge_query (filter)
- bricks/posts/query_vars (filter)
- bricks/query/loop_object (filter)
- bricks/query/loop_object_id (filter)
- bricks/query/loop_object_type (filter)
- bricks/query/no_results_content (filter)
- bricks/query/before_loop (action)
- bricks/query/after_loop (action)