Understanding the Query Block and Its Importance in Site Editing

I really don’t understand this Query block even though it’s been mentioned in several Tavern posts. My eyes seem to gloss over when reading about it – ha!

Is it important that regular WordPress users understand this block, or is it really a block for developers?


I have given the Query block a lot of attention as of late. On occasion, I may have even called it one of the largest hurdles the Gutenberg development team has needed to jump before block-based themes become a reality. However, the “query” WordPress term is not something all users or Tavern readers are familiar with. It is a concept as old as WordPress and generally something that only developers needed to familiarize themselves with. When Full Site Editing lands in WordPress, the new block will expose the Query to far more users as part of the site editor interface.

It is a block that is currently a part of the Gutenberg plugin but not WordPress core. However, at some point in 2021, more and more end-users and developers will be working with it.

In WordPress terminology, we are really talking about two things, the Query and the Loop. The Query is defined by a set of arguments or options that determine what posts to display. The Loop is the part of the machine that “loops” through the queried posts and displays them, one after another. The Query asks for posts; the Loop cycles through them.

Traditionally, theme authors were responsible for adding the Loop code to their templates, which used the global Query that WordPress supplied. Themes could also create custom queries, such as adding a posts list widget, categorized homepage post sections, or anything. And, “posts” can be anything from normal blog posts to WooCommerce products to the latest topics from the bbPress plugin.

The Query may be one of the single most important aspects of WordPress. In essence, it is the engine behind displaying the content of every page on the site. Without it, all WordPress sites would simply be a header and a footer.

The Gutenberg plugin provides two blocks for the Query:

  • Query: The outer block for setting the options for which posts will show.
  • Query Loop: The inner block, which is automatically added when using Query.

Currently, users can select between four fairly standard variations when first adding the Query block. They are combinations of the post featured image, title, date, and excerpt.

Initial Query block variations in the WordPress editor.
Query block variations.

These can be further customized via the block options panel in the sidebar. Users can also find “view” options in the toolbar for selecting between List and Grid views. The List view is the traditional list of posts flowing vertically down the page. The Grid view displays posts in two to six columns.

Grid view of the Query block in the WordPress editor.
Grid view of posts while using the Query block.

The Query block has a basic set of options for which post types to display and how to order them. It has filters for categories, tags, authors, and keywords. The block is not as robust as what is possible with code yet. It is missing some basic options like a post number limit and nearly all of the more advanced parameters. However, it is a promising starting point.

The more exciting aspects of this feature for end-users may not be the Query block at all. It is customizing the blocks that go inside, which display things like the featured image, post title, and more.

As a former theme author, I cannot count the number of times users have asked me about customizing some aspect of the posts layout. Having them dive into code to make minor changes, such as removing the post author name or displaying the category in a different place, was not an ideal experience. The site editor will put this power directly into each user’s hands.

Customized version of the Query block while in grid view.
Adding post-related blocks to the Query block in Grid view.

The comment by Marcus was on the Tavern’s post covering Gutenberg 9.6. The latest version of the plugin introduced global query inheritance for the Query block. This means that theme authors can now replicate the content layer in block-based themes. Previously, pages like archives and search results would simply display the latest posts when a theme used the Query block. Now, each of those pages can display the correct posts.

However, the Query block is so much more than that. In the hands of users, it can be a powerful tool for creating custom output on a homepage — think newspaper-style categorized sections. Users can also create post lists in a sidebar, such as the latest forum replies or products. Theme authors can offer templates or block patterns with unique designs or as starting points for end-users to modify. There is no shortage of possibilities.


11 responses to “Understanding the Query Block and Its Importance in Site Editing”

  1. More than a decade back I had introduced a concept in my repository-hosted theme, called “Ad hoc widget areas”. This was before page builders, and at a time when it was OK to bundle widgets and shortcodes in themes.

    The concept was easy – you could configure these widget areas to display any number of columns, and they could include from an assortment of widgets.

    One of the widgets I used to bundle was called “Query Posts”, which used to behave pretty much like the Query block – you could display posts as regular posts, excerpts, magazine-style content, large tiles with just the featured image, lists etc. You could pull from different post types, specify different criteria (tags, categories etc.), include / exclude posts, order them using any of the standard ways etc. Pretty much the only difference with the current Query block was that the UI was more textual (with form fields etc.) as opposed to graphical.

    The combination of the “Ad hoc Widget Areas” and the “Query Posts” widget was quite a hit with users of the theme.

    Glad to see that WP is finally catching up and offering some of this bundled within the core. While I intensely dislike the Gutenberg interface and the amount of bloat Gutenberg introduces (the first plugin I install on every new site is “Disable Gutenberg”), I am fully on board with two things in particular about it:
    * The concept of presenting blocks as comments (eliminating nasty surprises such as shortcode markup upon deactivation).
    * Bundling many of these much needed constructs into the core. While many concepts in the core have been abandoned after being introduced with much fanfare, things such as the Query block are likely to keep getting the attention that they deserve.

  2. Thanks for this Justin, it’s very useful in showing how I could add a Query block in a post or page.

    What I don’t get – possibly because it’s not been ‘done’ yet – is how archives can be generated using blocks. An annual or category/tag archive would be an excellent use of the Query block, along with headings and other text – and much easier to construct than dipping into code – and I could probably create those using Pages.

    But if I use ‘pretty’ permalinks, how to I get WordPress to generate the correct year/month/day archive? Based on what I’ve read so far there isn’t yet a way to do this. Do I stick with the existing files, but manually add blocks code? Am I missing something?

    • When Gutenberg 9.6 landed, the Query block got the ability to inherit the archive query. There’s an option named “Inherit query from the URL” in the block options sidebar panel. It will do just that. So, if you’re editing an category template, for example, you could tick that option to show the correct posts for that category.

      Themes will already have this block in place in their templates and configured to do this. You might not see it working correctly in some existing block-based themes yet since this just went in. They will probably need to be updated.

    • Steve,
      You need to enable FSE (full site editing) (https://make.wordpress.org/core/2020/12/10/status-check-site-editing-and-customization/) in order to use the query block (a few other other blocks become available as well).

      Note that enabling FSE will cause changes to your website and theme; so I would recommend to only use it on a testing environment where you feel comfortable experimenting on.

      There is a proposed solution to decouple the query block so it doesn’t require full-site editing see https://github.com/WordPress/gutenberg/pull/27822

      Decoupling the query block from the full site editing experience would be extremely advantageous. Theme developers and users can begin using it, share feedback, and find its faults (and advantages) with the architecture of the block.

      In fact, I’m wrapping up a project this week and would have used the query block if it was more polished; I didn’t feel comfortable to put live into a somewhat critical website as soon as next week.

  3. Hey Justin,

    Thanks for this write-up as well as the many others diving into Gutenberg. I posed a question in the #fse-outreach-experiment and #core-editor channels in WordPress slack, that I’d love to get your opinion on, too.

    “Howdy! I’m playing with Posts List block in TT1-Blocks theme and had a question.

    Traditionally in WP, a blog archive is generated by creating an empty Page and selecting Settings > Reading > and selecting that page as the posts page.
    With the introduction of the Posts List block, a posts archive (the output, if not the template anyway) could be mimicked with blocks.

    Is there a “best practice” or preference for creating a post archive in the FSE world?”


  4. The way I see it, the title field is always there, and you have the date, excerpt, and image options as optional. So, the variation step could be omitted in favor or radio buttons that would show/hide the three optional fields. That way, it would be easier to switch layouts.

    Also, having recently faced a similar issue on a website, I’d say that perhaps it would be worth considering an option to override the title, excerpt and even the image of an entry, if the user wants to. Here’s what I mean: https://www.dropbox.com/s/53pkvfkqxs2zx09/gutenberg-story.gif?dl=0

    On the example above, you can override the title, excerpt, and image and toggle the author. Maybe something similar would make sense to the Query Block as well. I found it to be particularly useful when it comes to image overriding, as many times, the featured image that is used in the fullstory isn’t the best fit for an entry in the frontpage.

    • The variations that the Query block shows when it is first inserted is just a starting point.

      If users do not want to have the date, excerpt, or any other element displayed on the page, then they can remove them–all of these page elements are blocks.

      Furthermore users can also add blocks to the Loop if they wanted too, or change the settings or the styles being used.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: