Summarize this article with:
Displaying dynamic content in WordPress used to require PHP knowledge. Not anymore.
Understanding what is a query loop in WordPress gives you the power to build blog archives, portfolio grids, and custom post displays without touching code.
The block editor handles everything visually.
This guide covers how the Query Loop block works, its nested blocks, configuration options, and practical applications.
You will learn to filter posts by category, add pagination, customize layouts, and troubleshoot common issues.
Whether you are building a news section or showcasing products, this block transforms how you display content across your WordPress site.
What Is a Query Loop in WordPress
A query loop in WordPress is a block that displays posts, pages, or custom post types dynamically based on parameters like category, tag, author, or publish date.
The block editor pulls content from your database and loops through matching results automatically.
Users need this when building blog archives, portfolio sections, news feeds, or any page requiring content that updates without manual editing.
WordPress introduced this feature in version 5.8 as part of full site editing.
Think of it as WPQuery without writing PHP code. The visual interface handles everything.
This guide covers the core functionality, configuration options, nested blocks, and practical applications. You will learn how to display posts dynamically, filter by taxonomy, configure query parameters, and add pagination to your layouts.
Prerequisites
Before working with the Query Loop block, verify these requirements:
- WordPress 5.8 or later (check Dashboard > Updates)
- Block editor enabled, not Classic Editor plugin
- Basic familiarity with Gutenberg blocks
- Access to Site Editor for template editing (block themes only)
- 5-10 minutes for initial setup
If you need to enable the Gutenberg editor in WordPress, do that first.
Classic themes can use Query Loop on pages and posts. Block themes unlock template-level usage.
How Does the Query Loop Block Work?
The Query Loop block translates WPQuery parameters into a visual interface. You select what content to display, the block queries your database, then iterates through each matching post to render the nested blocks inside.
No PHP required. No theme file editing.
Core Mechanism
Query parameters define which posts to fetch. The loop iterates through results. Nested blocks display the content for each post.
The block handles:
- Post type selection (posts, pages, custom post types)
- Taxonomy filtering by categories and tags
- Author and keyword filters
- Sort order and sticky post handling
- Pagination when results exceed items per page
Why This Matters
Before WordPress 5.8, displaying dynamic post lists required theme development or plugins.
Now the block editor gives you the same control visually. Content updates automatically as you publish new posts matching your query settings.
What Is the Difference Between Query Loop and Latest Posts Block?
Both blocks display posts. The similarities end there.
Latest Posts Block offers limited parameters, predefined display options, and no nested block customization. Quick to set up, but rigid.
Query Loop Block provides full query control, works with any post type, supports nested blocks for complete layout customization, and includes pagination.
Quick Comparison
| Feature | Query Loop | Latest Posts |
| Custom post types | Yes | No |
| Nested blocks | Yes | No |
| Pagination | Yes | No |
| Layout control | Full | Limited |
| Setup time | Longer | Faster |
Use Latest Posts for simple recent post lists. Use Query Loop when you need control over what displays and how.
What Nested Blocks Exist Inside the Query Loop?
The Query Loop block contains child blocks that pull and display post data. Each nested block serves a specific purpose.
Post Template Block
The container for all other nested blocks. This defines what renders for each post in the loop. Grid and list layout options live here.
Post Title Block
Displays the post title with optional link to the full post. Typography and color settings available in the sidebar.
Post Excerpt Block
Shows a short excerpt from each post. You can customize the “read more” link text and excerpt length.
Post Featured Image Block
Pulls the featured image assigned to each post. Supports aspect ratio controls, link options, and overlay settings.
Post Date Block
Displays published date. Format options include relative dates, custom formats, and optional linking back to the post.
Post Author Block
Shows author name, avatar, and bio. Configure visibility of each element in block settings.
Pagination Block
Adds previous/next navigation when results span multiple pages. Contains sub-blocks for page numbers, previous link, and next link.
You can add tables in WordPress inside the Post Template if your content requires structured data display within each loop item.
How Do You Add a Query Loop Block to a Page?
Two methods work in the block editor.
Method 1: Click the block inserter (+), navigate to Theme blocks, select Query Loop.
Method 2: Type /query-loop in a new paragraph and press Enter.
The block appears with layout selection options. Choose a pre-built pattern or click “Start Blank” for full control.
Template Editing
For site-wide loops, access Appearance > Editor > Templates. The Index template typically contains a Query Loop by default in block themes.
Page-level Query Loops work independently from template loops. Use the Site Editor when you want changes across all archive pages.
How Do You Configure Query Parameters?
Select the Query Loop block and open the Settings sidebar. Toggle “Inherit query from template” off to unlock custom parameters.
Post Type Selection
Choose posts, pages, or any registered custom post type from the dropdown. WooCommerce products appear here if the plugin is active.
Order and Sorting Options
Sort by date (newest/oldest) or alphabetically by title. The Order dropdown controls ascending or descending sequence.
Sticky Posts Handling
- Include: Sticky posts appear in normal position
- Exclude: Sticky posts hidden from results
- Ignore: Included but not treated as sticky
- Show only: Display sticky posts exclusively
Filter Options
Narrow results using categories, tags, authors, or keywords. Custom taxonomies appear when registered for the selected post type.
Multiple filters combine with AND logic. Posts must match all selected criteria.
How Do You Customize Display Settings?
Click the display settings icon in the Query Loop toolbar.
Items Per Page
Set how many posts display before pagination triggers. Maximum 100 per page. Lower numbers improve page load times.
Offset Value
Skip a set number of posts from the beginning. Offset 3 hides the first three matching posts. Useful when featuring recent posts elsewhere on the page.
Max Pages for Pagination
Limit total paginated pages. Setting this to 5 means users cannot navigate beyond page 5, regardless of total posts.
Grid vs List Layout
Select the Post Template block, then choose grid or list from the toolbar.
Grid view adds column controls in the sidebar. The layout adapts for responsive design automatically on smaller screens.
What Are Query Loop Block Patterns?
Block patterns provide pre-configured layouts for the Query Loop. Select one during block insertion to skip manual setup.
Available Default Patterns
- Title & Date
- Title & Excerpt
- Title, Date & Excerpt
- Image, Date & Title
- Large Title
Each pattern loads specific nested blocks in a ready-to-use arrangement. Modify any pattern after insertion.
How Do You Use Query Loop with Custom Post Types?
Custom post types appear in the Post Type dropdown when registered with showinrest = true.
Select your CPT from Settings > Post Type. Apply taxonomy filters specific to that post type.
Portfolio items, testimonials, products, events all work. The nested blocks pull metadata from whatever post type you select.
If your CPT does not appear, check the registration code. REST API support is required for block editor compatibility.
How Do You Add Pagination to Query Loop Results?
Pagination splits results across multiple pages when posts exceed the Items Per Page setting.
Steps to add:
- Open List View (three horizontal lines icon)
- Expand Query Loop > Select Post Template
- Click (+) inside Post Template
- Add Pagination block
The Pagination block contains three optional sub-blocks: Previous Page, Page Numbers, Next Page.
Add or remove sub-blocks based on your navigation needs. Style each independently.
What Happens When Query Returns No Results?
The Query No Results block displays when no posts match your query parameters.
Find it nested inside Query Loop in List View. Add custom text, images, or a search block to help visitors.
Empty queries happen with overly restrictive filters or categories containing no published posts. Good fallback messaging prevents dead ends.
Query Loop Block Settings Reference
Toolbar Options
- Display settings (items, offset, max pages)
- Replace pattern
- Grid/List toggle (on Post Template)
Sidebar Settings
- Layout controls and content width
- Query inheritance toggle
- Post type and filter configuration
- Color and spacing (varies by nested block)
Advanced tab accepts custom CSS classes for targeted styling.
Common Query Loop Configurations
Blog Archive Layout
Post type: Posts. Order: Date descending. Pattern: Image, Date & Title. Add Pagination block. Standard blog index setup.
Category-Specific Post Grid
Filter by single category. Grid layout with 3 columns. Items per page: 9. Useful for category landing pages.
Author Posts Section
Filter by specific author. Display on author bio pages or team member profiles. Include Post Author block for consistency.
Related Posts by Tag
Filter by shared tag. Exclude current post using offset or custom code. Place below single post content in templates.
Consider adding internal links in WordPress within your loop content to connect related posts.
Troubleshooting
Issue: Query Loop shows no posts
Solution: Verify post type selection, check filter settings match published content, confirm posts exist and are not drafts.
Issue: Pagination not appearing
Solution: Confirm total posts exceed Items Per Page value. Add Pagination block manually to Post Template.
Issue: Custom post type not listed
Solution: Check CPT registration includes showinrest => true. Flush permalinks at Settings > Permalinks > Save.
Issue: Layout breaks on mobile
Solution: Reduce grid columns, test with smaller viewport, check nested block dimension settings.
Issue: Featured images not displaying
Solution: Verify posts have featured images assigned. Check Post Featured Image block exists in Post Template. If you want to hide the featured image in WordPress posts intentionally, remove that nested block.
Related Processes
- Creating custom post types with REST API support
- Using Full Site Editing with block themes
- Extending Query Loop with Block Variations API
- Building WooCommerce product loops
- Understanding WordPress templates vs themes for proper Query Loop placement
FAQ on What Is A Query Loop In WordPress
What is a query loop in WordPress?
A query loop is a block that displays posts, pages, or custom post types dynamically based on specific parameters.
It queries your database and loops through matching content, rendering nested blocks for each result without PHP code.
When was the Query Loop block added to WordPress?
WordPress introduced the Query Loop block in version 5.8, released July 2021.
It arrived as part of full site editing, giving users visual control over dynamic content previously requiring theme development.
Can I use Query Loop with custom post types?
Yes. Any custom post type registered with showinrest = true appears in the Post Type dropdown.
Products, portfolios, testimonials, and events all work with the Query Loop block.
What is the difference between Query Loop and Latest Posts block?
Query Loop offers full query control, nested block customization, pagination, and custom post type support.
Latest Posts provides simpler setup with limited parameters. Use Query Loop when you need flexibility.
How do I add pagination to a Query Loop?
Open List View, expand Query Loop, select Post Template, then add the Pagination block inside.
Configure Previous Page, Page Numbers, and Next Page sub-blocks based on your navigation needs.
Can I filter posts by category in Query Loop?
Yes. Open Settings sidebar, scroll to Filters, and select specific categories or tags.
Multiple taxonomy filters combine with AND logic, meaning posts must match all selected criteria.
Does Query Loop work with classic WordPress themes?
Query Loop works on individual pages and posts in classic themes.
Template-level usage requires block themes. Classic themes can still display dynamic post lists within the Gutenberg editor.
What nested blocks are available in Query Loop?
Post Template contains Post Title, Post Excerpt, Post Featured Image, Post Date, Post Author, and Pagination blocks.
Add or remove nested blocks to customize what displays for each post in the loop.
How do I display posts in a grid layout with Query Loop?
Select the Post Template block inside Query Loop. Click the grid icon in the toolbar.
Adjust column count in the sidebar settings. The layout adapts automatically on mobile devices.
Why is my Query Loop not showing any posts?
Check your filter settings match published content. Verify the selected post type has posts.
Confirm “Inherit query from template” is toggled correctly. Overly restrictive filters cause empty results.
Conclusion
The Query Loop block changed how WordPress users display posts dynamically. No PHP required. No theme file editing.
You now understand how to configure query parameters, work with nested blocks like Post Template and Pagination, and filter content by taxonomy.
Grid layouts, custom post types, sticky post handling, and author filters are all within reach through the Site Editor.
WordPress 5.8 brought this functionality to Gutenberg, and it keeps improving with each release.
Start with a simple blog archive layout. Experiment with category-specific grids. Build author showcase sections.
The block handles the database queries. You focus on the design.
Full site editing makes template-level control accessible to everyone, not just developers.
