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.
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.phpor 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 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 => 2rendered 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.
