WordPress Terms Query Block Tutorial: Dynamic Taxonomy Displays for Category Navigation

WordPress 6.9 “Gene,” released December 2, 2025, introduces the Terms Query Block, a native solution for displaying categories, tags, and custom taxonomies. If you’ve struggled to create dynamic category navigation without plugins or custom code, this WordPress Terms Query Block tutorial walks you through the fundamentals and shows how to build WooCommerce product category grids with clickable images.

By the end, you’ll know how to configure the block for blog categories and extend it to e-commerce product navigation using the Block Bindings API.

Understanding the Block Structure

The Terms Query Block uses a nested architecture similar to the Query Loop block, but designed specifically for taxonomy terms rather than posts.

Core components:

• Terms Query (core/terms-query): The parent container that holds query configuration
• Term Template (core/term-template): Defines the layout for each term (list or grid)
• Term Name (core/term-name): Displays the term title with optional link
• Term Count (core/term-count): Shows associated post or product counts
• Term Description (core/term-description): Optional description display

The block supports all public taxonomies registered with show_in_rest: true, including WordPress categories, tags, and custom taxonomies from plugins like WooCommerce.

Two initial variations are available when inserting the block: Name only and Name & Count. From there, switch between list and grid layouts using the toolbar controls.

Basic Implementation Steps

Follow these steps to add a category navigation section to your site:

Step 1: Access the Site Editor

Navigate to Appearance > Editor in your WordPress dashboard. Block themes are required for full Site Editor access.

Step 2: Insert the Terms Query Block

Open the page or template where you want category navigation. Click the inserter (+) and search for “Terms Query.” Select either the Name only or Name & Count variation.

Step 3: Select Your Taxonomy

In the block settings sidebar, choose your taxonomy from the dropdown. Options include Categories, Tags, and any custom taxonomies registered on your site.

Step 4: Configure Query Settings

Adjust the query parameters:

Setting	Options	Use Case
Order by	Name A-Z, Name Z-A, Count High-Low, Count Low-High	Sort alphabetically or by popularity
Show empty terms	On/Off	Display categories with zero posts
Show nested terms	On/Off	Include child categories
Max terms	0-100	Limit displayed categories

Step 5: Choose Your Layout

Toggle between list view (stacked) and grid view (columns) using the toolbar. Grid layouts work well for visual category navigation with multiple columns.

WooCommerce Product Category Navigation

The Terms Query Block works with WooCommerce’s product_cat taxonomy, enabling native product category displays without third-party plugins.

Setting Up Product Categories

1. Insert the Terms Query Block on your Shop page template
2. Select “Product categories” from the taxonomy dropdown
3. Switch to grid layout for visual navigation
4. Add Term Name and Term Count blocks inside the Term Template

This creates a functional category grid, but WooCommerce product categories often have thumbnail images that enhance navigation. Displaying these images requires the Block Bindings API.

Adding Category Images with Block Bindings

WooCommerce stores category thumbnails as term meta. To display them, register a custom block binding source. Add this code to your theme’s functions.php file or a site-specific plugin:

// Add to functions.php or custom plugin
register_block_bindings_source(
    'custom/product-category-image',
    array(
        'label' => __('Product Category Image', 'theme-textdomain'),
        'get_value_callback' => function($source_args, $block_instance) {
            $term_id = $block_instance->context['termId'] ?? get_queried_object_id();
            $thumbnail_id = get_term_meta($term_id, 'thumbnail_id', true);
            return wp_get_attachment_url($thumbnail_id);
        },
        'uses_context' => array('termId'),
    )
);

After registering the binding, add an Image block inside your Term Template and bind its src attribute to the custom/product-category-image source through the block settings.

Important: This approach requires familiarity with Block Bindings API concepts. Category images are not automatic and must be configured through this custom binding.

Styling and Customization Options

The Term Template block provides comprehensive styling controls through the block settings sidebar.

Typography and Colors

Apply font family, size, weight, and line height to term names. Set text and background colors for the entire template or individual term blocks.

Grid Layout Adjustments

When using grid view, control the number of columns through the layout settings. Combine with gap controls to adjust spacing between category cards.

Spacing Controls

Adjust margin and padding on the Term Template to create visual separation. Block gap settings control the space between individual terms.

Saving as a Reusable Pattern

Once configured, save your Terms Query setup as a pattern for reuse across templates:

1. Select the Terms Query block
2. Open the options menu (three dots)
3. Select “Create pattern”
4. Name and save for future use

This ensures consistent category navigation across your site without recreating the configuration.

When to Use the Terms Query Block

The Terms Query Block addresses specific navigation needs better than existing alternatives.

Ideal Use Cases:

• Blog category index pages: Display all categories with post counts and descriptions
• E-commerce category navigation: Build visual product category grids for shop pages
• Custom taxonomy directories: Create listings for locations, brands, topics, or any custom taxonomy
• Tag exploration pages: Show popular tags sorted by count

Comparison with Existing Blocks:

Feature	Terms Query Block	Categories Block	Tag Cloud Block
Multiple taxonomies	Yes	No	No
Custom taxonomies	Yes	No	No
Grid layout	Yes	No	Limited
Full styling control	Yes	Limited	Limited
Block Bindings support	Yes	No	No

Choose the Terms Query Block when you need flexibility across multiple taxonomies, advanced layout options, or integration with custom data through Block Bindings. The Categories Block and Tag Cloud remain useful for simple sidebar widgets where basic functionality suffices.

Getting Started

The Terms Query Block brings flexible taxonomy displays to WordPress core, eliminating the need for custom code or plugins for most category navigation use cases. Start by adding it to a blog archive template with standard categories. Once comfortable with the configuration options, extend to WooCommerce product categories using the Block Bindings approach for thumbnail images.

---

Sources: WordPress 6.9 Documentation, Terms Query Block Official Guide, Brian Coords WooCommerce Tutorial