Query Loop block (original) (raw)

Go back to the list of Blocks

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.

Query loop block in the editor

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:

image showing the query loop anatomy

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.

Adding a 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:

Query loop block placeholder

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.

Choosing a query loop block pattern

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.

Adding a blank query loop block

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:

It’s also possible to add text or blocks when the Query Loop block returns no results:

No results text for query loop block

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:

Query loop block toolbar

Transform to

Transform to tool for query loop block

Click on the “Transform” button to convert the Query Loop block into a “Group” or “Columns” block.

Drag icon

Drag tool for query loop block

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

Move handles for query loop block

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

Alignment tool for query loop block

Use the change alignment tool to align the Query Loop block. Choose one of the following options:

The “Wide width” and “Full width” alignment settings must be enabled by your WordPress theme.

Display settings

Display settings for query loop block

Use the display settings tool to change various options for the Query Loop block. Choose one of the following options:

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.

List view tool for query loop block

Grid view

Displays your posts in a grid view.

Grid view tool for query loop block

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.

Block settings button in the editor

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:

Customizing query loop block color

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.

Customizing query loop block with content width

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

Sticky posts

This option allows you to choose between three options:

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.

Filtering query loop block

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:

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.

Advanced settings for query loop block

Resources

Changelog