Query Loop Block – Build Custom Post Grids, Portfolios & Archives (Complete Guide)

The most powerful block in Gutenberg – and the one that replaces dozens of plugins.

I remember spending hours searching for a plugin that could display my latest blog posts in a nice grid. Then another plugin for related posts. Another for a portfolio grid. Another for testimonials.

My site became slow, my dashboard cluttered, and I was constantly worried about plugin conflicts.

Then I discovered the Query Loop block.

This single, native WordPress block does all of that – and more – without any plugins. No coding. No performance bloat.

---

What Is the Query Loop Block? (Understanding the Logic)

Before Gutenberg, displaying dynamic posts meant writing PHP or using widgets with limited placement.

The Query Loop block does three things:

1. Query – “Ask the WordPress database: give me posts that match these rules”
2. Loop – “For each post, repeat this design template”
3. Output – “Render them as HTML, styled exactly how I want”

This is the same logic your blog archive page uses. But now, you can put it anywhere – homepage, inside a post, in a sidebar, in your footer – and customize everything visually.

Key concept: Parent and Children

• Query Loop (parent) – defines which posts to get (filters, order, number)
• Post Template (child) – defines how each post looks (image, title, date, excerpt)
• Pagination (child) – adds navigation below the grid
• No Results (child) – shows a message when no posts match

Think of it as a smart container that automatically fills itself with content.

---

Step 1: Adding a Basic Query Loop (2 Minutes)

Let’s build your first grid – the 6 most recent posts, 3 columns.

1. Open any page or post in the WordPress editor.
2. Click the plus (+) button and search for “Query Loop” (or type /query).
3. WordPress offers starter patterns. Choose “Grid” or “List” – I recommend Grid.
4. By default, it shows 10 posts. Change that to 6 in the right sidebar (Number of items).
5. That’s it – you now have a working post grid.

Quick settings reference:

Setting	Options	What it does
Number of items	1–100	How many posts to show (default 10)
Offset	Number	Skip first N posts (e.g., offset 1 skips the latest post)
Order by	Date, Title, Random, Comment count, etc.	Sort order
Order	Descending (newest first), Ascending	Newest first is standard for blogs

---

Step 2: Customizing How Each Post Looks (Post Template)

The default grid looks fine, but you can make it yours.

Inside the Query Loop block, you’ll see a Post Template block. This is where the magic happens. Click inside it – you can add, remove, or reorder blocks.

Typical Post Template structure (what I use):

text

[Group block] ← optional card styling (background, border, shadow, hover)
   ├── [Post Featured Image] (with link to post)
   ├── [Group block] ← text container
        ├── [Post Title] (H3, linked)
        ├── [Post Date] (with calendar icon)
        ├── [Post Terms] (categories as badges)
        ├── [Post Excerpt] (limited to 15–20 words)
        └── [Post Read More] (button or text link)

Each block’s key settings:

Inner block	Key settings I recommend
Post Featured Image	Aspect ratio: 16:9 or 4:3 (for consistency), link to post = yes
Post Title	Heading level: H3, link = yes, color = your theme’s primary
Post Date	Format: “F j, Y” (e.g., April 20, 2026), add icon (calendar)
Post Terms	Taxonomy: categories, separator: “, ” (or make them badges with CSS)
Post Excerpt	Max words: 15–20, preserve default or manual excerpt
Post Read More	Text: “Read more →”, style: link or outline button

Pro tip: To make each post card look like a card, wrap everything inside a Group block. Then give the group a background color (white), border radius (8px), and shadow (small). Add a hover effect if you like (requires a bit of CSS, but doable).

---

Step 3: Filtering Posts (The Real Power)

Without filters, Query Loop shows all posts. That’s boring. Let’s narrow it down.

In the right sidebar, find the Filters section. You can combine multiple conditions.

By Category (most common)

• Include – only posts from specific categories.
• Exclude – hide posts from specific categories.

Use case: Your homepage has a “Latest News” section – filter by category “News”. Or a “WordPress Tutorials” section – filter by category “WordPress”.

By Tag

Same logic as categories. Good for topic‑specific lists.

By Author

Show posts only from specific authors. Great for multi‑author blogs.

By Post Type

Default is “Posts”. Change to “Pages” (for a list of your static pages), “Products” (WooCommerce), or any custom post type (like “Portfolio Items” or “Testimonials”).

Use case: Portfolio grid – set Post Type = “Portfolio Items”.

By Keyword / Search

Enter a search term. The block shows posts containing that word in title or content.

Use case: A “Search results” page template (advanced).

By Custom Field (Advanced)

If you use Advanced Custom Fields (ACF) or Pods, you can filter by meta values. For example, show only posts where “featured” custom field equals “yes”. This requires knowing the meta key.

Exclude current post

For related posts, you often want to exclude the post the reader is currently viewing. In Filters, under “Post In/Exclude”, you can manually enter post IDs, or (if your theme supports dynamic data) use [post_id]. More on this in Example 3.

---

Step 4: Pagination – Don’t Show 100 Posts on One Page

If you set Number of items = 20, all 20 will load at once. That’s slow and overwhelming. Add pagination.

Below the Post Template, add the Pagination block.

Pagination settings:

Type	Best for
Standard (page numbers)	Archives, blog homepages
Load More button	Infinite scroll effect (requires JavaScript, works in modern themes)
Previous / Next links	Minimalist, good for sidebars

Pro tip: Always show total pages (“Page 1 of 5”) so readers know how much content exists.

---

Step 5: No Results Block – Handle Empty Queries

---

Real‑World Example 1: Blog Homepage with 3‑Column Grid

Goal: Display 9 latest posts from all categories, in a responsive 3×3 grid, with featured image, title, date, and short excerpt.

Steps:

1. Add Query Loop block, choose Grid starter.
2. Set Number of items = 9.
3. Order by = Date, Order = Descending (newest first).
4. Inside Post Template, build:
   • Group (white background, border radius 8px, padding 20px)
   • Post Featured Image (aspect ratio 16:9, link to post)
   • Post Title (H3, link)
   • Post Date (format “F j, Y”)
   • Post Excerpt (20 words)
   • Post Read More (“Read more →” as text link)
5. Add Pagination block below (Standard type).

Result: A professional blog homepage without any page builder.

---

Real‑World Example 2: Portfolio Grid (Custom Post Type)

Let’s say you added a custom post type “Portfolio” (using a plugin like CPT UI or ACF).

Goal: Display 6 portfolio items in a 2‑column or 3‑column grid, each with square image, title, and category.

Steps:

1. Add Query Loop block.
2. In Filters → Post type → select “Portfolio Items”.
3. Number of items = 6.
4. Inside Post Template:
   • Group (card styling)
   • Post Featured Image (aspect ratio 1:1 for square)
   • Post Title (H3, link)
   • Post Terms (taxonomy = portfolio categories, displayed as badges)
5. Pagination optional (if you have more than 6).

Result: A beautiful portfolio page that automatically updates when you add new projects.

---

Real‑World Example 3: Related Posts on Single Post

This one’s trickier but completely doable.

Goal: On each blog post, show 3 related posts from the same category, excluding the current post.

Method (works in block themes like Kadence):

1. Edit your Single Post template (Appearance → Editor → Templates → Single Post).
2. Below the post content, add a Query Loop block.
3. In Filters → Categories → choose “Same as current post” (if your theme supports this dynamic option; Kadence does).
4. In Exclude → add [post_id] to exclude the current post (again, dynamic data).
5. Number of items = 3.
6. Order by = Random (so related posts change each visit).
7. Design the Post Template simply – title only, or title + date.

If your theme doesn’t support dynamic data:
Manually select a category (e.g., “WordPress”) and manually exclude post IDs. That’s less dynamic but works as a static related section.

Alternative: Use a dedicated Related Posts plugin if this feels too complex. But for most modern block themes, the dynamic method works beautifully.

---

Real‑World Example 4: Testimonials as Posts

Instead of a separate testimonial plugin, write each testimonial as a regular post under category “Testimonials”.

Goal: Display 4 testimonials in a 2‑column grid, with customer name (title), testimonial text (excerpt), and optional rating (custom field).

Steps:

1. Create category “Testimonials”.
2. Write posts in that category. Title = customer name. Content/excerpt = testimonial text.
3. Add Query Loop block.
4. Filters → Categories → “Testimonials”.
5. Number of items = 4.
6. Inside Post Template:
   • Remove Post Featured Image (unless you have customer photos)
   • Post Title (H4, no link)
   • Post Excerpt (full testimonial text – increase excerpt length to 100 words if needed)
   • Post Date (optional – hide it)
7. No pagination needed.

Result: A testimonial grid that’s easy to manage.

---

Real‑World Example 5: Featured Posts on Homepage

Goal: Display 3 featured posts (marked with a “featured” tag or category) in a prominent section on your homepage.

Steps:

1. Create a tag “featured” (or category “Featured”).
2. Apply that tag to posts you want to highlight.
3. Add Query Loop block on your homepage.
4. Filters → Tags → select “featured”.
5. Number of items = 3.
6. Order by = Random (or Date).
7. Design Post Template larger – maybe wider images, longer excerpts.
8. No pagination.

Result: A dynamic “Editor’s Picks” section.

---

Advanced Tips I Wish I Knew Earlier

Tip 1: Aspect ratio is your friend

In Post Featured Image settings, set a fixed aspect ratio (16:9, 4:3, 1:1). This prevents images from breaking your grid layout when they have different sizes.

Tip 2: Use Group for card hover effects

Wrap Post Template contents in a Group. Give it a transition and subtle box‑shadow. On hover, change shadow or slightly lift the card (requires custom CSS, but very easy).

Example CSS (added to Additional CSS in customizer or theme):

css

.wp-block-group.post-card:hover {
    transform: translateY(-4px);
    box-shadow: 0 10px 20px rgba(0,0,0,0.1);
    transition: all 0.2s ease;
}

Tip 3: Limit excerpt length globally

Instead of manually setting excerpt length per Query Loop, install a small plugin or add code to functions.php. But per‑block is fine for most.

Tip 4: Combine Query Loop with Columns

Put a Query Loop inside a Columns block. Left column: intro text. Right column: latest posts. Beautiful two‑column homepage sections.

Tip 5: Use “Inherit query from template” when editing archives

If you’re editing your blog archive template (Appearance → Editor → Templates → Blog), turn ON “Inherit query from template” in the Query Loop block. This respects the main WordPress query (including search, pagination, etc.).

---

Common Mistakes (And How to Avoid Them)

Mistake 1: No pagination on long lists

If you show 50 posts without pagination, the page becomes huge and slow. Always add pagination for more than 12 posts.

Mistake 2: Ignoring mobile

A 4‑column grid looks great on desktop but becomes unreadable on a phone. Use responsive columns via Group block and media queries. Better yet, stick to 2 or 3 columns max.

Mistake 3: Forgetting “No Results”

Remove the default “No results” message and replace it with something helpful. Readers won’t know why nothing appears.

Mistake 4: Over‑filtering

Combining 5 filters (category + tag + author + custom field + search) can make the database query slow. Test performance. For most use cases, 1–2 filters are enough.

Mistake 5: Not linking the title

Every post in the grid should link to the single post. By default, Post Title links. But if you remove it, add a “Read More” button or make the featured image link.

---

Query Loop vs. Post Grid Plugins – Why Native Wins

Aspect	Query Loop (native)	Post Grid plugins (e.g., Post Grid, Content Views)
Performance	No extra CSS/JS bloat	Often adds heavy scripts
Customization	Full control via Post Template	Limited to plugin’s design options
Filters	Categories, tags, authors, custom post types, custom fields	Usually only basic
Pagination	Built‑in	Sometimes limited
Support for custom post types	Yes	Often paid feature
Learning curve	Requires 20 minutes to learn	Easier initially
Future‑proof	Part of WordPress core	Depends on plugin updates

My verdict: Invest the 20 minutes to learn Query Loop. You’ll never need a post grid plugin again.

---

What’s Next in This Series?

You’ve mastered dynamic post listings. Now let’s cover the rest of the block ecosystem:

• Theme Blocks – Navigation, Site Logo, Site Title, Query Loop (done), Post Template (done)
• Block Patterns & Reusable Blocks – save and reuse layouts across your site
• Full Site Editing (FSE) – editing headers, footers, and templates visually

👉 Next article: Theme Blocks & Full Site Editing – Navigation, Site Logo, Template Editor & Global Styles

---

What will you build with Query Loop? A portfolio? A testimonials section? A related posts area? Let me know in the comments – I’d love to see your examples.

---

📌 Key Takeaways (for skimmers)

• Query Loop replaces dozens of post‑listing plugins – it’s native, fast, and flexible.
• Filters let you show posts by category, tag, author, custom post type, even custom fields.
• Post Template controls how each post looks – image, title, date, excerpt, categories, read more.
• Always add Pagination when showing many posts.
• No Results block prevents empty sections.
• Real‑world uses: blog grids, portfolios, related posts, testimonials, featured content.
• Avoid over‑filtering, ignoring mobile, and forgetting to link titles.

---

🔗 Internal Links

• Article #1 – Gutenberg & Blocks: Why This Is the New Standard
• Article #4 – Design Blocks (Groups, Columns, Spacing)
• Article #7 – Theme Blocks & Full Site Editing (coming soon)