Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Explainer

What Is a WordPress Query Loop? Explained

What Is a WordPress Query Loop? Explained

Short answer

A WordPress query loop is the Query Loop block, a core block that pulls a list of posts from your database and shows each one using a template you design. You pick the post type, order, filters and number of posts, then add blocks such as title, image and excerpt inside it.

Key takeaways

  • The Query Loop block is the visual version of the classic PHP loop.
  • Its Post Template block repeats once for every post the query returns.
  • Use the default query in archive and search templates, and a custom query elsewhere.
  • It works in posts, pages and every block theme template.
  • Developers extend it with block variations and the query_loop_block_query_vars filter.

What is a WordPress query loop?

A WordPress query loop is the Query Loop block, a block that fetches a list of posts from your database and displays each one using a layout you design with other blocks.

It arrived in WordPress 5.8 and is the block-editor version of what developers call the loop in PHP themes. Instead of writing code, you pick which posts to show and how each one should look.

You can use it to build:

  • A blog page showing your latest posts
  • A grid of recent articles on the home page
  • A list of posts from one category
  • A portfolio of a custom post type
  • Archive and search result templates in block themes

The Query Loop block documentation on WordPress.org describes each setting. This article explains what the block is, how it works and when to use it.

How does the Query Loop block work?

The block runs a database query based on its settings, then repeats the design inside its Post Template block once for every post the query returns.

Think of it as two parts working together. The outer block decides which posts. The inner template decides what each post looks like.

When the page loads, WordPress reads the block's settings and builds a query. Behind the scenes it uses the same WP_Query class that PHP themes use. Each post in the result then fills the template.

If the query finds nothing, the block can show a No Results message instead. That is handy on search pages and empty categories.

Developers who want the PHP side can read our guide on how to use WP_Query. The block simply puts a visual layer on top of it.

What blocks sit inside a Query Loop?

A Query Loop contains a Post Template block, and usually Pagination and No Results blocks, with post-level blocks such as Title and Featured Image placed inside the template.

Here is how the pieces fit together:

BlockWhere it sitsWhat it does
Query LoopOuter wrapperHolds the query settings
Post TemplateInside Query LoopRepeats for each post
Post Title, Excerpt, Date, Featured ImageInside Post TemplateShow data for the current post
PaginationInside Query Loop, after the templateAdds next and previous links
No ResultsInside Query LoopShows when nothing matches

You can add almost any block inside the Post Template. Groups, columns, buttons and spacers all work. Post-specific blocks such as Post Author or Post Terms read data from the current post in the loop.

What settings can you change in a Query Loop?

You can choose the post type, sort order, number of posts, filters by category, tag, author or keyword, and whether the block follows the page's own query.

Select the Query Loop block and open the settings sidebar. The main options are:

  • Query type. Use the template's default query, or set a custom one. Older versions call this the Inherit query from template toggle.
  • Post type. Posts, pages or any public custom post type.
  • Order by. Newest, oldest, A to Z or Z to A.
  • Sticky posts. Include, exclude or show only sticky posts.
  • Filters. Narrow by taxonomy terms, author or keyword.
  • Items per page and offset. Set how many posts show and skip the first few.

The block toolbar also has a layout switch between a list and a grid view, with a column count for grids.

Settings shift between WordPress releases. If an option is missing, update WordPress or check the block reference in the Block Editor Handbook.

What does the default query option mean?

The default query option tells the block to use whatever posts WordPress already loaded for the current page, such as a category archive or search results.

This is the setting you want in templates. On a category archive, the loop then shows posts from that category automatically. On a search template, it shows the search results.

With a custom query, the block ignores the page context and runs its own fixed query. That is better for a home page section such as Latest from the blog, where you always want the same type of list.

A common mistake is using a custom query on an archive template. Every category then shows the same posts. Switch the template's loop back to the default query to fix it.

Where can you use the Query Loop block?

You can use it in posts, pages, synced patterns and every template in a block theme's Site Editor.

In a classic theme, the block works in the post and page editor. Many people use it to build a custom blog section on a landing page.

In a block theme, the block powers templates such as Index, Home, Archive and Search. Open the Site Editor, edit a template and you will usually find a Query Loop already in place.

If you are not sure which kind of theme you have, our comparison of block themes and classic themes explains the difference.

Our guide to the Latest Posts block covers a simpler block that lists recent posts with fewer options.

How is the Query Loop different from the Latest Posts block?

The Latest Posts block shows a fixed list of recent posts with a few display toggles, while the Query Loop lets you design every part of each item and query any post type.

Use Latest Posts for a quick sidebar or footer list. Use Query Loop when you need a custom layout, a custom post type, pagination or archive support.

Query Loop takes a little longer to set up. In return, you control spacing, image size, meta details and buttons for each post.

How do developers extend the Query Loop block?

Developers extend it with block variations that preset the query and the query_loop_block_query_vars filter that changes the query on the front end.

A block variation is a saved version of the block with preset attributes. For example, a plugin can register a Products variation that already queries a product post type. Since WordPress 6.1, variations can use a namespace attribute so the plugin can detect its own blocks.

To change the query in PHP, use the query_loop_block_query_vars filter. It passes the query arguments before WordPress runs them, so you can add meta queries or other changes.

The block's source code lives in the Gutenberg repository on GitHub. Our guide to WordPress hooks explains how filters work if you are new to them.

What are common Query Loop problems?

The usual problems are duplicate posts across loops, the wrong posts on archives, broken pagination and custom post types that do not appear.

Quick fixes for each:

  • Same posts on every archive. Switch the loop to the default query.
  • Duplicates across two loops on one page. Use the offset setting on the second loop.
  • Pagination shows the same posts. Only one loop per page should handle pagination, usually the default query.
  • Custom post type missing. The post type must be public and registered with REST support. See our guide to creating a custom post type.

If the editor preview looks right but the front end does not, clear your page cache before you dig deeper.

Should you use the Query Loop block?

Yes, if you want a custom post list without writing PHP, or if you use a block theme where it is the standard way to show posts.

It is flexible, part of WordPress core and needs no plugin. For very complex filtering, a small custom block variation or a filter in PHP usually solves the gap.

If you want to learn more about block editing in general, Learn WordPress has free lessons on the Site Editor and its blocks.

Frequently asked questions

Is the Query Loop block the same as the WordPress loop?

They do the same job in different ways. The classic loop is PHP code in theme files that runs through posts. The Query Loop block does this visually in the editor, using the same underlying query class, so you can design the output without code.

Do I need a block theme to use the Query Loop block?

No. You can add a Query Loop block to any post or page in the block editor, even with a classic theme. A block theme adds the ability to use it inside site templates such as the blog index, archives and search results.

Can the Query Loop block show WooCommerce products?

It can query public post types, and WooCommerce adds its own product collection blocks built on the same idea. For store pages, the WooCommerce product blocks usually give better product-specific options such as price and add to cart buttons.

How many posts can a Query Loop show?

You set the number of items per page in the block settings, and you can add pagination for more. Very large numbers slow the page, so keep it to a sensible count and let pagination handle the rest.

Why does my Query Loop show the same posts on every category page?

The loop is probably using a custom query instead of the default query. A custom query ignores the page context. Edit the archive template, select the loop and switch it to use the default query from the template.

Sources

  1. Query Loop block WordPress.org Documentation
  2. query_loop_block_query_vars hook WordPress Developer Resources
  3. Core blocks reference Block Editor Handbook
  4. Query block source GitHub

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.