Query Loop Block

The Query Loop block displays dynamic content from elsewhere on your site, such as posts, pages, or custom content types. “Dynamic” means the block updates automatically as new content is published, so you can build listings that stay current without editing the page each time.

Why use the Query Loop block

Use the Query Loop block when you want to:

  • Display a list or grid of curated content on a page
  • Feature recent posts, news, events, resources, or other content types
  • Automatically show new content as it is published
  • Filter results by category, tag, author, keyword, or other criteria

A Query Loop is especially useful when the content should stay up to date over time.

Note: If you want to display related content on a single post, use the dedicated Related Posts block instead, which is likely already included as part of the post single template. This is a simpler option that automatically selects similar content without needing to configure a Query Loop.

The easiest way to use it

This block is powerful, but in most cases editors won’t need to build it from scratch. The easiest and most reliable approach is to start with an available pattern, then adjust the query settings to control what content appears.

When adding a new Query Loop block, you’ll usually see two starting options:

  1. Choose: Start with a pre-configured pattern
  2. Start blank: Build the layout manually

In most cases, start with Choose and select an available pattern. This gives you a ready-made structure and is the simplest way to work with the block.

The Pattern Library may also include pre-built layouts that already use Query Loop. When possible, start with one of those patterns instead of creating a new Query Loop from scratch.

Block structure

The Query Loop block is easier to use once you understand that it is really a group of nested blocks working together.

Query Loop block

This is the outer container. It controls what content is shown.Think of the Query Loop block as the part that answers: “Which content should appear here?”

This is where you choose things like:

  • Post type
  • Sort order
  • Number of items to display
  • Filters such as categories, tags, authors, or keywords

Post Template block

Inside the Query Loop block is the Post Template block. This controls how the results are arranged. Think of the Post Template block as the part that answers: “How should these results be laid out?”

This is where you choose:

  • List or Grid layout
  • Number of columns when using a grid layout

Post Card block

Inside the Post Template block, each result is displayed using a Post Card block. This block controls the presentation of each individual item in the loop. Think of the Post Card block as the part that answers: “What does each item look like?”

This is where you choose:

  • Heading level for the post title
  • Card layout, such as vertical or horizontal. In most cases Vertical layout is used with Grid and Horizontal layout is used with List.

Note: A Search Card block may also be used in some contexts, but this is typically reserved for search results templates.

Other supporting blocks

Some Query Loop structures may also include:

  • Pagination: Lets users move between pages of results
  • No Results: Displays a message if nothing matches the query

These are most commonly used in archive or search templates. When a Query Loop is added to regular page content, these blocks are often not needed.

In most cases, the best workflow is:

  1. Add a Query Loop block. Learn how to add blocks.
  2. Choose a pre-configured pattern
  3. Select the content type you want to display
  4. Set filters and sorting as needed
  5. Choose list or grid layout
  6. Adjust the number of items and columns
  7. Preview the results

This keeps the process manageable and avoids unnecessary complexity.

Query settings

When the Query Loop block is selected, the right sidebar includes the settings that control which content appears.

Query type

Choose how the Query Loop behaves. For most page content, use Custom.

  • Default is only used in archive templates and automatically handles the query.
  • Custom is typically used when the block is placed on a page and enables further query options.

Post type

Choose which content type to display. This is one of the most important settings, because it determines the source of the content shown in the loop.

Posts and Pages are typically available, however your site may have additional post types available.

Order by

Controls how results are sorted. In most cases, Newest to Oldest is the typical choice.

Sticky posts

Controls how sticky posts are handled. In most cases, Include is the typical setting.

Display options

Additional settings may be available under Display options, including:

  • Items per page: Choose how many items to display. Try to choose a number that works cleanly with your layout. For example, if you are using a 3-column grid, 3, 6, or 9 items will usually feel more balanced than 5.
  • Offset: Skips a set number of posts before displaying results. This is especially useful to avoid repeating the same posts when using multiple Query Loops on the same page with the same filters. This helps create unique layouts, such as two-column features post layouts.
  • Max pages to show: Limits how many pages of results can be displayed when pagination is used. This is most useful when a large amount of content exists, but only a limited set of recent results should be shown.

Filters

Additional filter controls can be added to narrow the results.

  • Taxonomy: Filter by categories, tags, or other taxonomy terms.
  • Authors: Filter content by specific authors.
  • Keywords: Filter by keywords found in the content.

Layout and display

Query Loop block

When the Query Loop block is selected, you control the width of the block..

Toolbar

  • Block width: Control how wide the carousel appears within the layout

Settings sidebar

  • Inner blocks use content width: Controls whether content inside the card is constrained to the default content width. This is typically disabled so the card can fill the full available space.

Post Template block

When the Post Template block is selected, you control how results are arranged.

Toolbar

  • List view / Grid view: Switch between list and grid layouts
  • Block width: This setting is available, but it’s usually best to control at the top level, Query Loop block.

Settings sidebar

  • Grid item position Controls how grid columns are set.
  • Auto allows the width to determine the number of columns automatically
  • Manual is usually the recommended option, because it lets you choose the number of columns directly. In most cases, 2 or 3 columns work best.

Post Card block

When the Post Card block is selected, you control how each result card is displayed.

Toolbar

  • Block width: Control how wide the card appears
  • Change design: Quickly switch between available card patterns, if more than one is available

Settings sidebar

  • Heading level: Sets the heading level used for the post title. Choose the heading level based on the page structure, not just the visual size. This helps maintain accessible heading order.
  • Card layout: Controls whether the card is displayed vertically or horizontally.

Styles

When using a ready-made Post Card or Search Card, most styling is already handled for you.

The Post Template block may include style controls like text color, font size, block spacing. These are only relevant when building a layout manually. In most cases, they are not needed when using the pre-configured card blocks.

Tips for editors

Start with a pattern

The Query Loop block can become complex quickly. Starting with a pattern is the easiest way to get a reliable result.

Focus on the query first

Before changing layout details, make sure the correct content is being displayed. Start with post type, filters, sorting, and item count.

Keep layouts simple

A clean 2- or 3-column grid, or a straightforward list, is usually the best choice. Simpler layouts are easier to scan and easier to maintain.

Use offset to avoid duplicates

If you are showing featured content and additional listings on the same page, Offset is one of the most helpful settings for keeping results from repeating.

Preview before publishing

Because this block pulls in live content dynamically, always preview the page to confirm the correct content appears and the layout feels balanced. The editor may display ‘Draft’ content, while the front end will only display ‘Published’ content.

  1. WordPress.org Query Loop block documentation – Please note that your implementation may include customizations that affect available settings or behavior.