WordPress

Query Loop

Query Loop is the core block that prints a list of posts from a query you configure in the editor. Post Title, Featured Image, and Excerpt are placed inside it as a template that repeats.

How it is measured

The block's attributes live in the block comment: post type, posts per page, order, orderBy, a taxonomy filter, and an inherit flag. With inherit true on an archive or search template, it uses the page's main query. With inherit false, it runs its own WP_Query with the parameters you set.

To see what ran, open Query Monitor and look at the queries attributed to the block render, or check the markup for <!-- wp:query {"queryId":3,...} -->. A developer can alter the query with the query_loop_block_query_vars filter.

Worked example

A conference site has 90 posts of a custom type called session. The organizer adds a Query Loop to the home page with post type session, 6 per page, ordered by date descending. Sessions with a future date still show first, because the date is the publish date, not the session date.

The developer adds a meta query through the query_loop_block_query_vars filter to order by a field named session_start. The block now lists the next 6 talks by start time.

How it differs

A Query Loop is a block that prints a list, while Gutenberg is the editor that provides blocks in general. Query Loop works with built-in post types and any custom post type with show_in_rest enabled. It does not filter by custom fields in the interface, so field-based ordering needs code.

Common errors

Leaving inherit on in a template for a single post. Setting posts per page to 100 on a home page. Forgetting that sticky posts and the offset can behave oddly with pagination. Placing two Query Loops with the same queryId so their pagination clashes. Using it for a post type that has show_in_rest off.

In practice

Check each Query Loop on your site for the post type and the page size. Try a second one on staging with a custom filter. If you need field-based ordering, add the filter in a small plugin, not in the theme.

See also

Gutenberg, Custom post type

Sources

Count this on a real site.

Watch my website