---
title: "How to Use Custom Query Filter to Create a Taxonomy List in WordPress?"
url: https://nexterwp.com/docs/use-custom-query-filter-to-create-a-taxonomy-list-in-wordpress/
date: 2024-11-29
modified: 2026-09-27
lang: en
author: "Aditya Sharma"
description: "The include, exclude and ordering settings cover most cases. Occasionally they do not — you want terms matching a meta value, or a rule that changes with the page. The..."
image: https://nexterwp.com/wp-content/uploads/2024/11/How-to-Use-Custom-Query-Filter-to-Create-a-Taxonomy-List-in-WordPress_-1024x519.jpg
word_count: 557
---

# How to Use Custom Query Filter to Create a Taxonomy List in WordPress?

## Key Takeaways

- Nexter Blocks Taxonomy Listing block creates a taxonomy list using a custom query filter in WordPress.
- Custom code adds a meta_query for person_id values 73227, 970674, and 17293 with relation set to OR.
- Taxonomy Listing block uses the Query tab’s Custom Query ID field, where tpgb_custom_taxo_query is entered to list the person id’s.

The include, exclude and ordering settings cover most cases. Occasionally they do not — you want terms matching a meta value, or a rule that changes with the page.

The custom query filter hands the block's term query to a WordPress filter of your naming, so you can change it in code.

*For every Taxonomy Listing setting in one place, see the [Taxonomy Listing guide](https://nexterwp.com/docs/add-taxonomy-listing-in-wordpress/).*

[LIVE BLOCK LINK](https://nexterwp.com/nexter-blocks/builder/wordpress-taxonomy-listing/)

## Before You Start

- **Edition:** **Pro** — the Taxonomy Listing block needs Nexter Blocks Pro.- **Block to enable:** Taxonomy Listing, switched on under **Nexter > Blocks** in your WordPress dashboard.- **Somewhere to put a small amount of PHP** — a child theme's `functions.php` or a site-specific plugin.- **Comfort with `get_terms()` arguments**, since that is what you are editing.

## Steps

- Enter a filter name of your choosing in the **custom query** field, then publish and add a matching filter in your code.

![The custom query ID field](https://nexterwp.com/wp-content/uploads/2026/09/tx-query-custom-id.webp)

> *The name is yours to pick. Use something specific, such as my_theme_category_query, so it cannot collide with another plugin's hook.*

## How It Behaves

Your filter receives the block's term query arguments and must return them. A worked example:

`add_filter( 'my_theme_category_query', function( $args ) { $args['number'] = 2; return $args; } );`

- **The filter is only applied if it exists.** Measured: with an ID set but no filter registered, the listing was unchanged at 6 terms. The block checks before calling.- **With a filter registered, it takes effect.** Measured: the same listing with a filter returning `number => 2` rendered **2** terms.- **You receive the whole argument array**, built from the block's settings — the taxonomy, count, offset, ordering, include and exclude lists. You can change any of it.- **You must return the array.** Returning nothing leaves the block with no arguments.- **It runs on every render**, so keep it cheap.- **Measured with Nexter Blocks Pro deactivated:** the block renders nothing at all — not a wrapper, not a message, zero output. This is a Pro-only block.

## Limitations

- **Pro only** — nothing renders with Pro deactivated.- **This is a developer feature.** A mistake here produces an empty listing with no message explaining why.- **Your filter overrides the block settings.** Someone editing the page later will change a setting and see nothing happen, with nothing on screen to tell them why. Leave a comment in the code.- **The block does not validate what you return.** An invalid argument array gives an empty result.- **It only shapes the term query.** It cannot change how the cards are rendered.- **A generic filter name risks collisions** with other code on the site.

## Troubleshooting

### My filter is not running

The name in the block and the name in `add_filter()` have to match exactly, and the filter has to be registered before the page renders. With no matching filter the block simply ignores the field.

### The listing went empty after I added the filter

Your callback probably does not return the arguments array, or returns something invalid. It must return the array it was given.

### Changing the block settings does nothing now

Your filter is overriding them. That is what it is for, but it is worth a comment in the code so the next person knows.

### Which arguments can I change?

Anything `get_terms()` accepts — the block builds an ordinary arguments array and hands it straight to you.

## Related Docs

- [Exclude a category by ID](https://nexterwp.com/docs/exclude-category-by-id-from-category-list-in-wordpress/)- [Create a custom taxonomy list](https://nexterwp.com/docs/create-a-custom-taxonomy-list-in-wordpress/)- [Add taxonomy listing in WordPress](https://nexterwp.com/docs/add-taxonomy-listing-in-wordpress/)- [Create a category grid](https://nexterwp.com/docs/create-category-grid-in-wordpress/)- [Advanced tab settings](https://nexterwp.com/docs/use-advanced-tab-in-nexter-blocks/)