Query Loop block

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

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:

  • Choose
  • Start blank
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:

  • 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:

No results text for query loop block

Block toolbar

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
  • Drag icon
  • Move arrows
  • Align
  • Display settings
  • Replace
  • List view/Grid view
  • More options

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


Alignment tool for query loop block

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

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:

  • 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.


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


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:


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

  • 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.


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
  • 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.

Advanced settings for query loop block



  • 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

Was this article helpful? How could it be improved?

First published

Last updated