The Query Loop Block

What the Query Loop block actually is: a visual wrapper around WP_Query. Configure its settings panel and WordPress runs a database query behind the scenes, then hands the results to a set of inner blocks that repeat once per post — the block-editor equivalent of writing a PHP loop, without writing one.

What it queries, and the setting that confuses everyone

A Query Loop has two fundamentally different modes, and mixing them up explains most "it's showing the wrong posts" reports. Inherit query from template makes the block reuse whatever the current URL already determines — an archive page inherits the archive's posts, a search results template inherits the search terms, a category page inherits that category. Custom query switches the block to its own independent settings: pick a post type, taxonomy terms, author, order, and the block ignores page context entirely.

The trap is that "inherit" looks like the safe default and is often enabled by default, so a Query Loop dropped onto what looks like a generic page can silently start pulling from whatever the template's main query happens to be, rather than the specific set of posts someone intended. Turning that setting off and configuring a custom query is the fix whenever the block needs to show a fixed, deliberate set of content rather than follow the page it sits on.

Filtering a custom query

These map directly onto WP_Query arguments — the settings panel generates the same query parameters a developer would otherwise write in PHP, just through form fields instead of an array.

The inner blocks: Post Template

Everything that repeats per post lives inside the block's Post Template inner block — Post Title, Featured Image, Excerpt, Post Date and similar blocks, usually arranged with Group, Row and Stack blocks into a card-like layout, each one meaningless outside that context because each depends on "the current post in the loop" the same way the_title() depends on being inside PHP's have_posts() loop. Rearranging those inner blocks changes the layout of every repeated item at once; there is no way to make one item in the loop look different from the rest without leaving the block entirely.

Pagination, and why it breaks on a static page

The Query Loop's pagination controls work by reading the page number out of the URL and asking the query for the matching offset. That relies on the block being part of the page's main templated query, which is reliably true on an archive or a blog index but is not guaranteed on a static page — particularly a page set as the static front page, where WordPress's usual paging structure for "page two" of a URL is not part of how a fixed page is normally addressed. A Query Loop with pagination dropped onto a static page can therefore show the first set of posts correctly and then fail to advance, or advance to a URL that renders the same content again. Placing paginated query loops on genuine archive templates, rather than on arbitrary pages, avoids the problem entirely — the same templates that typically also carry the site's header built from a Navigation block.

Performance of nested loops

Each Query Loop block issues its own database query, separate from the page's main query. That is invisible with one loop on a page, but a template with several independent Query Loop blocks runs that many additional queries on every load, and nesting one Query Loop inside another's post template multiplies the count further — a query per outer post rather than one query total. On a page with dozens of posts in the outer loop, an inner query per row is the kind of pattern that shows up clearly in a slow time-to-first-byte, worth checking for as part of any general pass covered in how to speed up a WordPress site.

What it cannot do that PHP can

The settings panel exposes the query arguments the editor team judged common enough to need a UI for. It does not expose arbitrary meta queries combining several custom fields with mixed comparison operators, cross-post-type relationship logic, or anything computed rather than declared. Those cases still need a block that calls WP_Query directly in PHP — either a custom block or a shortcode backed by the kind of code covered in how functions.php works — with the Query Loop reserved for the cases its interface actually covers.

Common mistakes

• Leaving "inherit from template" on by accident. The block then follows page context nobody intended it to follow.
• Expecting pagination to work on a static page. It is reliable on archive templates and unreliable elsewhere.
• Stacking several Query Loops on one template without checking query cost. Each one is a full extra database query.
• Nesting a Query Loop inside another's post template. That runs a query per outer post, not once.
• Reaching for a custom block before checking whether a custom query setting already covers the need. Most "I need PHP for this" cases turn out to be a filter already in the panel.

Verify

Open the block's settings and confirm whether "inherit from template" is on or off — that single toggle explains most unexpected result sets. If pagination is in use, click through to page two on the actual front end, not the editor preview, and confirm the URL and the results both change. On a template with multiple Query Loop blocks, check the number of database queries in a debugging tool per how to enable WordPress debug mode to confirm the query count matches expectations.