The WordPress Query Loop block gives site owners a visual way to create repeatable content listings in the block editor. Instead of building a loop with PHP code, you can define which content should appear, how it should be ordered, how many items should be displayed and how each result should look.
This makes the block useful for posts, pages and custom post types made available by the individual website configuration. You can begin with a pattern or a blank layout, refine the repeated Post Template, add filters and configure pagination or an empty-state message. The exact post types, taxonomies and controls available will depend on the selected content type, theme and active plugins, so the finished listing should always be tested on the front end.
What the WordPress Query Loop Block Is Useful For
When a Query Loop is a practical fit
The Query Loop displays content according to selected query parameters inside the block editor. It is a practical no-code option when a page needs a consistent listing of related content, such as posts, pages or an available custom post type. A repeated layout can include a title, image, excerpt, metadata and a read-more element, allowing visitors to scan several items in one place.
You can start from a ready-made pattern when you want an initial structure, or use a blank variation when the listing needs to be assembled more deliberately. The block can support uses such as resource, portfolio or directory-style listings when the relevant content type is available on the site. It should not, however, be presented as a replacement for every archive, directory or faceted-search solution. Its options are the controls exposed for the selected content and site configuration.
What can vary between websites
Two WordPress websites may not show the same Query Loop choices. Available post types and taxonomies depend on the content registered on the site, the selected post type, the theme and active plugins. A custom taxonomy may appear for one content type but not another, and a custom post type supplied by a plugin may require separate checks before it can be used in a public listing.
For that reason, treat the editor interface as site-specific. Do not design the whole listing around a filter or content type until you have confirmed that the relevant option is available and produces the expected front-end output.
Create the Listing from a Pattern or Blank Layout
Insert and choose a starting structure
Insert a Query Loop block on the page or template where the listing should appear. WordPress lets you choose a pattern or begin with a blank layout. A pattern can provide a useful starting arrangement, while a blank variation gives you more control over the structure from the beginning.
After inserting the block, select the outer Query Loop rather than one of its individual inner blocks. Use List View in the editor when necessary to inspect the hierarchy. This distinction matters because the outer block controls the query, while nested blocks control the presentation of each result.
Keep the initial structure simple. First confirm that the expected content is being returned. Then add filtering, layout refinements and navigation. Preview the listing on the front end before publishing rather than relying only on the editor canvas.
Understand the repeated Post Template
The Post Template is the repeating container inside the Query Loop. Its inner blocks are rendered for every matching result, so changes made inside this template are repeated consistently throughout the listing.
Common inner blocks include the post title, featured image, excerpt, date, author, categories, tags and read-more elements. The Post Template can also contain layout blocks such as Group, Columns or Row. Understanding this structure prevents a common mistake: editing an individual-looking item without realizing that the change defines every item in the loop.
Switch from Default to Custom Query Settings
Why the Custom query type matters
Select the outer Query Loop block and inspect its query settings. If the editor is showing only limited controls, change the Query Type from Default to Custom. The Custom setting exposes controls for the post type, ordering, display limits and filters.
This is an important troubleshooting step when you cannot find a custom post type selector or the Filters section. The absence of those controls does not automatically mean that the block is malfunctioning; the query may still be using Default mode. Interface labels and available choices can also vary between installations.
Set content type, order and display limits
With a Custom query selected, choose the required content type from the options available on that site. Standard choices can include posts and pages, while additional custom post types may be supplied by plugins or other site configuration. Select only a content type that has been checked for the intended public use.
Next, configure the order of the results. The documented choices include chronological and alphabetical ordering options. Display settings can control items per page, offset and the maximum number of pages to show. These settings determine which records enter the loop before the Post Template renders them.
After changing the content type, order or limits, inspect the published output. Confirm that the listing contains the expected records and that the number of visible items supports the intended page structure.
Add Category, Tag, Author and Keyword Filters
Taxonomy and author filtering
Open the Filters section after switching the Query Loop to Custom when necessary. Taxonomy filters can include categories and tags. Custom taxonomies may also appear when they are supported by the selected post type and made available by the site configuration, theme or active plugins.
Use the relevant taxonomy to narrow the listing to a specific content group. For example, a category or tag filter can restrict a post listing to related entries. Before relying on a custom taxonomy, confirm that it is connected to the selected post type and exposed in the editor.
An author filter restricts results to selected authors. This can be useful when the listing should represent content associated with particular contributors. The filter does not create authors or change the content; it narrows the query to the available author selections.
Keyword matching expectations
The keyword filter lets you enter search terms for the query. Be careful when explaining its behavior to editors or visitors: when more than one keyword is entered, the documented behavior requires every entered keyword to match. It should not be described as an either-or search in which matching just one term is sufficient.
Test restrictive combinations before publishing. A category, author or keyword filter may return no matching content, and that state should be handled deliberately with the optional No Results block. The exact filter controls available will depend on the selected post type and the configuration of the individual site.
Design List and Grid Layouts with Post Template
Choose List View or Grid View
To change the presentation of repeated results, select the nested Post Template block. Use its block toolbar to switch between List View and Grid View. List View stacks the results vertically, which can suit entries with longer excerpts or more metadata. Grid View presents results in columns and is suited to compact, repeated items.
When Grid View is selected, the block settings include a column-number control. Use that setting to define the grid arrangement offered by the editor, then preview the published page to confirm that the selected structure works with the actual content.
Build the repeated item design
Make layout changes inside the Post Template so they repeat for every result. Place the post title where it is easy to identify, then add a featured image, excerpt or metadata when those elements support the purpose of the listing. Dates, authors, categories, tags and read-more elements can be included as part of the repeated item.
For more structured cards or list items, compose the inner blocks with Group, Columns or Row. The important distinction is that these blocks shape each repeated result; they do not independently define which records the Query Loop retrieves. Check the front end after rearranging blocks because the final appearance depends on the content returned by the query.
Configure Pagination and No-Results Messages
Add and structure Pagination
If the result set may span multiple pages, keep the Pagination block when it is included in the selected pattern. If it is missing, add it manually inside the Query Loop. Pagination belongs within the Query Loop because it controls navigation through that loop’s result set.
The Pagination block can contain previous-page, page-number and next-page controls. You can use previous and next links, page numbers or both, depending on the structure of the listing. Adjust its layout and appearance in the editor, then test more than one page on the published site.
Full-page reload is described as the default behavior and is generally the safer choice for predictable navigation. If you change reload behavior, test navigation and accessibility carefully rather than assuming that the result will be identical on every site.
Keep a useful No Results state
The optional No Results section provides a fallback when the query returns no matching content. It appears on the published page only in that situation. Keep it in the structure when visitors may apply restrictive filters, and replace generic text with a clear explanation of what happened or what the visitor can do next.
A useful empty state makes it clear that the query returned no matching content rather than suggesting that the page is broken. Test it with restrictive category, author or keyword combinations before publishing. Also test the normal state and multiple pagination pages so the listing behaves correctly in both populated and empty conditions.
Troubleshooting and Site-Specific Limitations
When controls or content types are missing
If custom post type, ordering or filter controls are unavailable, first check whether the Query Type is still set to Default. Switch to Custom and inspect the options again. If a desired post type is still missing, do not assume that the Query Loop is at fault. The content may not be available to the editor, or the site configuration may not expose it for this query.
For a custom post type supplied by a plugin, confirm on that individual website that the content is publicly queryable and compatible with the editor. Check whether its relevant taxonomies are available as filters. Theme and plugin combinations can affect which post types, taxonomies and controls appear, so identical labels and results should not be assumed across installations.
The built-in block also does not establish performance benchmarks for large listings or complex taxonomies. Avoid promising a particular performance result without testing the actual site, content and configuration.
Pre-publish verification checklist
Before publishing, review the complete query and the front-end states it can produce. A short verification pass should include the following:
- Content: confirm that the selected post type returns the intended records.
- Filters: test category, tag, author and keyword combinations that are available for the selected content.
- Keywords: remember that multiple entered keywords must all match according to the documented behavior.
- Layout: check the Post Template in both the chosen list or grid arrangement and the actual published view.
- Pagination: open multiple pages and verify previous, page-number and next controls where used.
- Empty state: apply restrictive filters and confirm that the No Results message is clear.
- Site variation: verify the result with the active theme, plugins and site configuration rather than relying on assumptions from another installation.
The WordPress Query Loop block provides a practical editor workflow for custom listings without PHP code, but its usefulness depends on matching the query to the content available on the individual site. Insert the block, choose a pattern or blank layout, switch to Custom for query controls, select the content type, order and limits, then add the relevant filters. Design the repeated Post Template in List View or Grid View, add Pagination when needed and keep a useful No Results state.
Front-end testing is part of the setup, not an optional assumption. Check filtered results, empty results, multiple pagination pages and the final layout before publishing. Explore our WordPress plugins, WooCommerce extensions, themes and membership plans to find the right tools for your website.