- Article
- Intermediate
- 3 minutes read
- Reviewed August 3, 2026
A query loop displays a collection of content selected by rules rather than entered manually.
Instead of creating separate cards for every article, a query can request the latest posts, items from a taxonomy term or entries of a particular post type. The layout is defined once and reused for every result.
Dynamic Content vs Manual Content
Manual content is entered directly into a page and remains until an editor changes it.
Dynamic content is generated from current WordPress data. A latest-posts section updates when a new post is published. An event archive can reflect new entries and taxonomy filters without editing the archive page itself.
Dynamic output improves consistency and reduces duplicate maintenance.
The Query Loop Block
The Query Loop block provides a visual interface for displaying collections.
It contains inner blocks that define each result, such as:
- Post Title.
- Featured Image.
- Excerpt.
- Date.
- Author.
- Terms.
- Post Content.
- Read More.
The block repeats this inner template for every matching item.
Inherit Query vs Custom Query
In a template context, a Query Loop can inherit the main WordPress query.
This is appropriate for archives, search results and other routes where WordPress has already determined which items belong on the page.
A custom query uses its own settings to select content. This is useful for homepage sections, related resources or curated lists.
Do not replace the main archive query unnecessarily, because pagination, filters and context can become inconsistent.
Query Parameters
Depending on support and interface options, a query can filter or order content by:
- Post type.
- Taxonomy terms.
- Author.
- Keyword.
- Date.
- Sticky status.
- Parent relationship.
- Order and order-by value.
- Number of items.
More complex relationships or metadata queries may require custom code or specialized blocks.
Pagination and Empty Results
A complete loop should consider:
- Pagination.
- No-results state.
- Loading and performance.
- Duplicate items across sections.
- Accessible headings and link labels.
An archive should not simply disappear when no items match. Provide a useful message or alternative path.
Designing Reusable Result Cards
Keep card structure semantic and resilient.
- Use a logical heading level for item titles.
- Make links descriptive.
- Avoid fixed heights that break with longer text.
- Treat images as optional unless required by the model.
- Test missing excerpts and terms.
- Preserve focus order.
- Use presets for spacing and typography.
A pattern can help reuse the card design, while the query supplies changing records.
Performance Considerations
Every query has a cost.
Avoid loading large unpaginated collections or several expensive custom queries on one page. Images, taxonomy calculations and third-party blocks can add further work.
Use pagination, caching and appropriate database structures for large content sets.
Query Loops and Custom Content
Query Loops can display custom post types when those types are registered appropriately and exposed to the editor.
The theme still needs suitable templates and styles for the fields and relationships that define the content.
Frequently Asked Questions
Is Query Loop the same as the main WordPress query?
Not always. It can inherit the main query or run a separate custom query.
Can Query Loop filter by custom fields?
Core visual controls are limited. Advanced metadata queries often require code or an extension.
Why is pagination not working?
The loop may not inherit the expected query, multiple paginated loops may conflict or rewrite and cache behavior may need review.
Continue Learning
Previous: The WordPress Template Hierarchy