Query Loop block (original) (raw)
The Query Loop block is an advanced block that allows you to display posts based on specified parameters, like a PHP loop without the code. You can think of it as a more complex and powerful Latest Posts Block. With various block patterns integrated into the block setup, you can do things like create a portfolio or a page full of your favorite recipes.
Anatomy of the Query Loop block
The block inspector provides a quick overview of the Query Loop block’s structure. Each part gives you access to different settings:
- Query Loop: Configure the query parameters, such as post type or category.
- Post Template: Choose how the content is displayed, either in a list or grid format.
- Pagination: Select which navigation elements to include, such as next/previous buttons or page numbers.
- No Results: Set a message to display hen a query returns no results.
Adding the Query Loop block
To add the Query Loop block to a page, click the block inserter (+) icon to open the block inserter pop-up window and choose the Query Loop block.
You can also use the keyboard shortcut /query-loop to quickly insert a Query Loop block.
Detailed instructions on adding blocks
Block configuration
After adding the Query Loop block you will see two options:
- Choose
- Start blank
How to choose a pattern
If you select the Choose option, you will have various pattern options. Just select one that you like, and it will be added. Each Query Loop block is made up of various nested blocks, like the Post Title block and Pagination block, so depending on which pattern you choose, nested blocks can differ.
How to start blank
If you select the Start blank option, you’ll see four variations you can choose from. Select the one you want to use.
How to customize the appearance
There are numerous ways to customize the Query Loop block, partially because it’s made up of nested blocks that you can rearrange, add to, and more. When you customize one block in the Query Loop block, the changes will apply to all blocks of the same type. While customizing this block, it might help to use the List View found in the top toolbar. Here are some ideas for customization to get you started:
- You can change the width of various aspects of the Query Loop block.
- You can change the alignment of blocks within the Query Loop block.
- You can add blocks into the Query Loop block, like Post Author or Post Excerpt.
- You can rearrange the blocks to your liking, dragging and dropping or using the movers to do so.
- You can change the number of posts listed by selecting the Query Loop block and adjusting the Display Settings option in the block toolbar.
- You can set various color options for the nested blocks.
- You can add featured images by adding the Featured Image block.
It’s also possible to add text or blocks when the Query Loop block returns no results:
To view the block toolbar, click on the block, and the toolbar will be displayed.
Every block has unique toolbar icons and blocks specific user controls that allow you to manipulate the block right in the editor.
The Query Loop block shows nine buttons in the block toolbar:
- Transform to
- Drag icon
- Move arrows
- Align
- Display settings
- Replace
- List view/Grid view
- More options
Transform to
Click on the “Transform” button to convert the Query Loop block into a “Group” or “Columns” block.
Drag icon
To drag and drop the block to a new location on the page template, click and hold the rectangle of dots, then drag it to the new location. The blue separator line indicates where the block will be placed. Release the left mouse button when you find the new location to place the block.
Move arrows
The up and down arrow icons can be used to move the block up and down on the page.
Detailed instructions on moving a block within the editor can be found here
Align
Use the change alignment tool to align the Query Loop block. Choose one of the following options:
- None – leaves the block the current size.
- Wide width – increase the width of the block beyond the content size.
- Full width – extend the block to cover the full width of the screen.
The “Wide width” and “Full width” alignment settings must be enabled by your WordPress theme.
Display settings
Use the display settings tool to change various options for the Query Loop block. Choose one of the following options:
- Items per Page – Choose how many posts you want to show within the Query Loop block.
- Offset – Enable the Query Loop block to skip a certain number of WordPress posts before starting output.
- Max page to show – Limits how many pieces of content to show.
If you don’t see this section, it’s because you need to toggle off the “Inherit query from template” setting.
Replace
Use the replace option to replace the current pattern with a new one.
List view (default)
Displays your post in a stacked list.
Grid view
Displays your posts in a grid view.
Options
The Options button on a block toolbar gives you more features to customize the block.
Read about these and other settings.
Block Settings
The block settings panel contains customization options specific to the block. To open it, select the block and click the settings icon next to the Publish/Update button.
Here are the options for the Query Loop block:
Color
Starting from WordPress 6.2, the Query Loop block will no longer support color settings. As a result, you will need to change the colors of the individual blocks that are within the _Query Loop_block instead:
See this guide for more information about changing colors.
Inner blocks use content width
This option allows you to configure justification, content, and wide width settings for all nested blocks within the Query Loop block.
Inherit query from template
This is an option you can toggle on and off, depending on whether you want to customize the query the loop relies upon. WordPress will otherwise rely on the template being used to determine what posts appear. If you toggle it on, certain customization options will be hidden. If you toggle it off, more customization options will appear.
Post type
WordPress contains different types of content, and they are divided into collections called “Post types”. By default, there are a few different ones, such as blog posts and pages, but plugins could add more.
Order by
- Newest to Oldest (default)
- Oldest to Newest
- Alphabetical A to Z
- Alphabetical Z to A
Sticky posts
This option allows you to choose between three options:
- Include (default) – Displays sticky posts.
- Exclude – Removes sticky posts.
- Only – Shows only sticky posts.
Filters
This option allows you to customize further what posts are being displayed. If you don’t see this section, it’s because you need to toggle off the “Inherit query from template” setting.
- Categories – List any categories you want included.
- Tags – List any tags you want included.
- Authors – Search for an author and add it to the list, multiple authors are allowed.
- Keyword – Enter any keywords you want included.
Mind that custom taxonomies filtering is also possible. Check the following example for the WooCommerce product categories filter:
If you choose a hierarchical post type like Page, these options will be shown:
- Authors – Search for an author and add it to the list, multiple authors are allowed.
- Keyword – Enter any keywords you want included.
- Parents – List any parents you want included.
Advanced Settings
The advanced tab lets you add a CSS class to your block, allowing you to write custom CSS and style the block as you see fit. It also allows you to assign an HTML element.
Resources
Changelog
- Updated 2023-03-26
- Revised formatting for the whole article
- Added videos/screenshots where applicable
- Updated Block Settings Color section
- Updated Filters section flow along with new parent filter, multiple author, and custom taxonomies filtering
- Updated block creation and replacement flows
- Added a mention and a screenshot on customizing what is shown when the Query Loop block shows no results
- Added a link to Pagination block
- Updated all the screenshots for 6.2
- Added in resources section on 2021-07-14
- Created 2021-07-08