Title: Terms Query block
Author: annezazu
Published: December 2, 2025
Last modified: December 13, 2025

---

# Terms Query block

## In this article

 * [Requirements](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#requirements)
 * [Anatomy of the Terms Query block](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#anatomy-of-the-terms-query-block)
 * [Add the Terms Query block to a template](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#add-the-terms-query-block-to-a-template)
 * [Block configuration](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-configuration)
    - [How to customize the appearance](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#how-to-customize-the-appearance)
 * [Block toolbar](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-toolbar)
    - [Transform to](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#transform-to)
    - [Drag icon](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#drag-icon)
    - [Move arrows](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#move-arrows)
    - [Align](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#align)
    - [List view (default)](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#list-view-default)
    - [Grid view](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#grid-view)
    - [Options](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#options)
 * [Block Settings](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-settings)
    - [Inner blocks use content width](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#inner-blocks-use-content-width)
    - [Order by](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#order-by)
    - [Selected terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#selected-terms)
    - [Show empty terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#show-empty-terms)
    - [Show nested terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#show-nested-terms)
    - [Max terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#max-terms)
    - [Advanced Settings](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#advanced-settings)
 * [Demo](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#demo)
 * [Tips](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#tips)
 * [Frequently asked questions](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#frequently-asked-questions)
 * [Changelog](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#changelog)

[ Back to top](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#wp--skip-link--target)

The Terms Query block displays a list or grid of taxonomy terms (such as Categories,
Tags, or custom taxonomies). It’s most useful in templates (for example, a “Categories”
index or a directory page) where you want to list terms and design how each term
appears.

## 󠀁[Requirements](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#requirements)󠁿

 * WordPress 6.9 or later.
 * A block theme for editing templates in the Site Editor.
 * The taxonomy you want to display must be public and available in the editor (
   show_in_rest enabled).

## 󠀁[Anatomy of the Terms Query block](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#anatomy-of-the-terms-query-block)󠁿

![](https://wordpress.org/documentation/files/2025/11/Terms-query-anatomy.png)

The block inspector provides a quick overview of the _Term Query _block’s structure.
Each part gives you access to different settings:

 * **Terms Query:** Configure the query parameters.
 * **Term Template**: Choose how the content is displayed, either in a list or grid
   format.
 * **Term Name**: Show the term name.
 * **Term Description**: Show the term description.
 * **Term Count:** Show the number of results for each term.

## 󠀁[Add the Terms Query block to a template](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#add-the-terms-query-block-to-a-template)󠁿

 1. Go to Appearance > Editor.
 2. Open the template where you want the terms to appear (for example, a custom “Categories”
    template).
 3. Place your cursor in the desired location.
 4. Open the block inserter (+), search for “Terms Query,” and select it.

## 󠀁[Block configuration](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-configuration)󠁿

After adding the _Terms Query_ block you will see two options:

![](https://wordpress.org/documentation/files/2025/11/Terms-Query-block-options-
1024x393.png)

These variations offer two different layout options:

 * Name: just shows the name of the term.
 * Name & Count: shows the name and the number of items in that term.

### 󠀁[How to customize the appearance](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#how-to-customize-the-appearance)󠁿

There are numerous ways to customize the _Term Query block,_ partially because it’s
made up of nested blocks that you can rearrange, add to, and more. When you customize
one block in the _Term Query block_, the changes will apply to all blocks of the
same type. While customizing this block, it might help to use the List View found
in the top toolbar. Here are some ideas for customization to get you started:

 * You can **change the width** of various aspects of the _Term Query _block.
 * You can **change the alignmen**t of blocks within the _Term Query block._
 * You can **rearrange the blocks** to your liking, dragging and dropping or using
   the movers to do so.
 * You can **change the number of terms **listed by selecting the _Term Query _block
   and adjusting the Max Terms option in the block settings
 * You can **set various color options** for the nested blocks.
 * You can **change how the number of terms are displayed** by selecting the _Terms
   Number_ block and changing the format in the block toolbar.
 * You can **show the term description **by selecting the _Term Description _block
   and adjust the styles as needed.

## 󠀁[Block toolbar](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-toolbar)󠁿

To view the block toolbar, click on the block, and the toolbar will be displayed.
Every block has unique toolbar icons and blocks specific user controls that allow
you to manipulate the block right in the editor. The **Terms Query **block has the
following:

 * Transform to.
 * Align none, wide width, full width.
 * Move/drag to reposition in the template.
 * More options (duplicate, lock, remove, etc.).

### 󠀁[Transform to](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#transform-to)󠁿

Click on the “Transform” button to convert the _Query Loop_ block into a “Group”
or “Columns” block.  

![](https://wordpress.org/documentation/files/2025/11/transform-to-term-query.png)

### 󠀁[Drag icon](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#drag-icon)󠁿

To drag and drop the block to a new location, click and hold the rectangle of dots,
then drag it to the new location. The blue separator line indicates where the block
will be placed. Release the left mouse button when you find the new location to 
place the block.

![](https://wordpress.org/documentation/files/2025/11/drag-handles-term-query.png)

### 󠀁[Move arrows](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#move-arrows)󠁿

The up and down arrow icons can be used to move the block up and down on the page.

![](https://wordpress.org/documentation/files/2025/11/move-handles-term-query-.png)

Detailed instructions on moving a block within the editor can be found [here](https://wordpress.org/support/article/moving-blocks/)

### 󠀁[Align](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#align)󠁿

Use the change alignment tool to align the _Terms Loop _block. Choose one of the
following options:

 * **None – **leaves the block the current size.
 * **Wide width – **increase the width of the block beyond the content size.
 * **Full width – **extend the block to cover the full width of the screen.

The “Wide width” and “Full width” alignment settings must be enabled by your WordPress
theme. 

![](https://wordpress.org/documentation/files/2025/11/align-terms-query.png)

### 󠀁[List view (default)](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#list-view-default)󠁿

Displays your terms in a stacked list. Select the Term Template block to edit this.

![](https://wordpress.org/documentation/files/2025/11/Terms-query-list-1024x393.
png)

### 󠀁[Grid view](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#grid-view)󠁿

Displays your terms in a grid view. Select the Term Template block to edit this.

![](https://wordpress.org/documentation/files/2025/11/Terms-query-grid-1024x287.
png)

### 󠀁[Options](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#options)󠁿

The Options button on a block toolbar gives you more features to customize the block.

[Read about these and other settings.](https://wordpress.org/support/article/more-options/)

## 󠀁[Block Settings](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#block-settings)󠁿

### 󠀁[Inner blocks use content width](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#inner-blocks-use-content-width)󠁿

This option allows you to configure justification, content, and wide width settings
for all nested blocks within the Query_Loop_ block.

### 󠀁[Order by](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#order-by)󠁿

 * Name: A > Z
 * Name: Z > A
 * Count: High to Low
 * Count: Low to High

### 󠀁[Selected terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#selected-terms)󠁿

This option lets you pick specific taxonomies to show. Simply search and select 
what to add.

### 󠀁[Show empty terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#show-empty-terms)󠁿

This option lets you display terms even if they are empty. This is off by default.

### 󠀁[Show nested terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#show-nested-terms)󠁿

This option lets you display nested terms. This is off by default.

### 󠀁[Max terms](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#max-terms)󠁿

This option lets you limit the number of terms you want to show. To show all terms,
use 0 (zero).

### 󠀁[Advanced Settings](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#advanced-settings)󠁿

The advanced tab lets you add a CSS class to your block, allowing you to write custom
CSS and style the block as you see fit. It also allows you to assign an HTML element.

## 󠀁[Demo](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#demo)󠁿

## 󠀁[Tips](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#tips)󠁿

 * Use List for hierarchical taxonomies; use Grid for scanning many terms quickly.
 * Keep Term Name prominent; add Term Description for context on landing pages.
 * Use Hide empty to avoid blank archives and keep the list relevant.
 * Save a configured Terms Query section as a Pattern to reuse across templates.

## 󠀁[Frequently asked questions](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#frequently-asked-questions)󠁿

**Can I show only top-level terms?**

 * Yes. Leave Parent unset and turn Include subterms off.

**Can I display a custom taxonomy?**

 * Yes, if it’s public and registered to show in the editor (show_in_rest true).

**Can I link the term name to its archive?**

 * Term Name typically links to the term archive by default. You can control additional
   links (like Term Count) in its block settings.

## 󠀁[Changelog](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#changelog)󠁿

 * Created 2025-12-02

## Was this article helpful? How could it be improved? 󠀁[Cancel reply](https://wordpress.org/documentation/article/terms-query-block/?output_format=md#respond)󠁿

[Log in to submit feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fwordpress.org%2Fdocumentation%2Farticle%2Fterms-query-block%2F&locale=en_US).
If you need support with something that wasn't covered by this article, please post
your question in the [support forums](https://wordpress.org/support/forums/).

First published

December 2, 2025

Last updated

December 13, 2025