Extending the Query Loop Block

The Query Loop block is a powerful tool for displaying lists of posts. By creating custom variations, you can provide users with preset configurations tailored to specific post types or use cases.

Why Create Variations?

Most users don’t need to understand technical query concepts. A pre-configured variation provides:

Clear, branded block names and descriptions
Sensible defaults for your post type
Focused settings without irrelevant options
Better discoverability in the block inserter

Use block variations to create user-friendly versions of the Query Loop block without exposing complex technical concepts.

Creating a Basic Variation

Here’s a complete example for a “Books List” variation:

import { registerBlockVariation } from '@wordpress/blocks';

const MY_VARIATION_NAME = 'my-plugin/books-list';

registerBlockVariation( 'core/query', {
  name: MY_VARIATION_NAME,
  title: 'Books List',
  description: 'Displays a list of books',
  icon: 'book',
  isActive: ( { namespace, query } ) => {
    return (
      namespace === MY_VARIATION_NAME &&
      query.postType === 'book'
    );
  },
  attributes: {
    namespace: MY_VARIATION_NAME,
    query: {
      perPage: 6,
      postType: 'book',
      order: 'desc',
      orderBy: 'date',
      inherit: false,
    },
  },
  scope: [ 'inserter' ],
} );

Key Properties

namespace Attribute

The namespace attribute identifies your variation:

attributes: {
  namespace: 'my-plugin/books-list',
  query: {
    postType: 'book',
  },
}

Always use a unique namespace to prevent conflicts with other plugins. The namespace helps Gutenberg recognize your specific variation.

isActive Property

Define when your variation is considered active:

isActive: ( { namespace, query } ) => {
  return (
    namespace === MY_VARIATION_NAME &&
    query.postType === 'book'
  );
}

Or use the shorthand for simple namespace matching:

isActive: [ 'namespace' ]

scope Property

Set scope: [ 'inserter' ] to make your variation appear in the block inserter:

scope: [ 'inserter' ]

Defining the Layout

Using innerBlocks

Provide default inner blocks to skip the setup phase:

innerBlocks: [
  [
    'core/post-template',
    {},
    [
      [ 'core/post-title' ],
      [ 'core/post-excerpt' ],
      [ 'core/post-date' ],
    ],
  ],
  [ 'core/query-pagination' ],
  [ 'core/query-no-results' ],
]

Using Patterns

Alternatively, register patterns connected to your variation:

register_block_pattern(
  'my-plugin/book-list-pattern',
  [
    'title' => 'Book Grid',
    'blockTypes' => [ 'core/query/my-plugin/books-list' ],
    'content' => '<!-- wp:query {"namespace":"my-plugin/books-list"} -->',
  ]
);

Connect patterns to your variation by adding core/query/$variation_name to the pattern’s blockTypes property.

Controlling Available Settings

allowedControls Property

Limit which settings users can modify:

allowedControls: [ 'inherit', 'order', 'taxQuery', 'search' ]

Available controls:

inherit - Allow inheriting query from template
postType - Post type selector
order - Sort order (asc/desc)
sticky - Sticky posts handling
taxQuery - Taxonomy filters (inclusion and exclusion)
author - Filter by author
search - Keyword search
format - Post format filter
parents - Parent entity filter

Remove the postType control when users should only see your custom post type. This prevents confusion and potential errors.

Adding Custom Controls

Use a block filter to add custom inspector controls:

import { addFilter } from '@wordpress/hooks';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, SelectControl } from '@wordpress/components';

const withBookControls = ( BlockEdit ) => ( props ) => {
  const { attributes, setAttributes } = props;
  
  // Only show for our variation
  if ( attributes.namespace !== 'my-plugin/books-list' ) {
    return <BlockEdit { ...props } />;
  }

  return (
    <>
      <BlockEdit { ...props } />
      <InspectorControls>
        <PanelBody title="Book Settings">
          <SelectControl
            label="Book Author"
            value={ attributes.query.bookAuthor }
            options={ [
              { label: 'All Authors', value: '' },
              { label: 'Tolkien', value: 'tolkien' },
              { label: 'Asimov', value: 'asimov' },
            ] }
            onChange={ ( bookAuthor ) => {
              setAttributes( {
                query: {
                  ...attributes.query,
                  bookAuthor,
                },
              } );
            } }
          />
        </PanelBody>
      </InspectorControls>
    </>
  );
};

addFilter(
  'editor.BlockEdit',
  'my-plugin/with-book-controls',
  withBookControls
);

Custom Query Parameters

Add custom parameters to the query object:

attributes: {
  query: {
    postType: 'book',
    bookAuthor: 'J. R. R. Tolkien',
    genre: 'fantasy',
  },
}

Front-End Implementation

Handle custom parameters with the query_loop_block_query_vars filter:

add_filter(
  'query_loop_block_query_vars',
  function( $query, $block ) {
    // Only modify our variation
    if ( 'my-plugin/books-list' !== $block['attrs']['namespace'] ) {
      return $query;
    }

    // Add custom meta query
    if ( ! empty( $block['attrs']['query']['bookAuthor'] ) ) {
      $query['meta_query'] = [
        [
          'key' => 'book_author',
          'value' => $block['attrs']['query']['bookAuthor'],
        ],
      ];
    }

    return $query;
  },
  10,
  2
);

Editor Preview

Handle custom parameters in the REST API for editor previews:

add_filter(
  'rest_book_query',
  function( $args, $request ) {
    $book_author = $request->get_param( 'bookAuthor' );
    
    if ( ! empty( $book_author ) ) {
      $args['meta_query'] = [
        [
          'key' => 'book_author',
          'value' => $book_author,
        ],
      ];
    }

    return $args;
  },
  10,
  2
);

Custom query parameters are automatically passed to the REST API. Use the rest_{post_type}_query filter to handle them in editor previews.

Understanding taxQuery

The taxQuery attribute supports both inclusion and exclusion:

query: {
  taxQuery: {
    include: {
      category: [ 1, 2, 3 ],
      post_tag: [ 10, 20 ],
    },
    exclude: {
      category: [ 5, 6 ],
      post_tag: [ 15 ],
    },
  },
}

Users will see both “[Taxonomy]” (inclusion) and “Exclude: [Taxonomy]” controls when taxQuery is in allowedControls.

Complete Example

Here’s a full implementation:

registerBlockVariation( 'core/query', {
  name: 'my-plugin/books-list',
  title: 'Books List',
  description: 'Display a curated list of books',
  icon: 'book',
  attributes: {
    namespace: 'my-plugin/books-list',
    query: {
      perPage: 6,
      postType: 'book',
      order: 'desc',
      orderBy: 'date',
    },
  },
  innerBlocks: [
    [
      'core/post-template',
      {},
      [
        [ 'core/post-featured-image' ],
        [ 'core/post-title' ],
        [ 'core/post-excerpt' ],
      ],
    ],
    [ 'core/query-pagination' ],
  ],
  allowedControls: [ 'order', 'search' ],
  isActive: [ 'namespace' ],
  scope: [ 'inserter' ],
} );

With this variation, users get a fully functional books list without needing to understand query parameters or post types.

Get Started

Development Environment

Core Concepts

Block Development

Data & State

Guides

Extending the Query Loop Block

Why Create Variations?

Creating a Basic Variation

Key Properties

namespace Attribute

isActive Property

scope Property

Defining the Layout

Using innerBlocks

Using Patterns

Controlling Available Settings

allowedControls Property

Adding Custom Controls

Custom Query Parameters

Front-End Implementation

Editor Preview

Understanding taxQuery

Complete Example

​Why Create Variations?

​Creating a Basic Variation

​Key Properties

​namespace Attribute

​isActive Property

​scope Property

​Defining the Layout

​Using innerBlocks

​Using Patterns

​Controlling Available Settings

​allowedControls Property

​Adding Custom Controls

​Custom Query Parameters

​Front-End Implementation

​Editor Preview

​Understanding taxQuery

​Complete Example

Why Create Variations?

Creating a Basic Variation

Key Properties

namespace Attribute

isActive Property

scope Property

Defining the Layout

Using innerBlocks

Using Patterns

Controlling Available Settings

allowedControls Property

Adding Custom Controls

Custom Query Parameters

Front-End Implementation

Editor Preview

Understanding taxQuery

Complete Example