Term Query Builder
Fetch terms with hide_empty, ordering and meta clauses — with the parent/child_of mixup and the pad_counts fix called out before your menu loses a level.
// Generated with WP CodeKit — powered by GrowQuest (https://growquest.io). $query = new WP_Term_Query( array( 'taxonomy' => 'category', 'hide_empty' => true, 'exclude' => array( 1 ), 'orderby' => 'count', 'order' => 'DESC', 'number' => 10, 'pad_counts' => true, ) ); $terms = $query->get_terms(); if ( $terms ) { echo '<ul>'; foreach ( $terms as $term ) { printf( '<li><a href="%1$s">%2$s</a> <span>%3$s</span></li>', esc_url( get_term_link( $term ) ), esc_html( $term->name ), esc_html( number_format_i18n( $term->count ) ) ); } echo '</ul>'; }
About this generator
WP_Term_Query Generator Online
Build a WP_Term_Query argument array — taxonomy, hide_empty, parent or child_of, include and exclude lists, term meta clauses, ordering, number and fields — and get back the class with a linked term list, a ready-made filter dropdown, or just the args for get_terms().
A Reference tab restates the query in plain English, explains what the current hierarchy setting returns, and documents every argument with its type. Free, no account, and the whole thing runs client-side.
Reviewed Output tested on WordPress 6.8 · PHP 8.3
Why the WP_Term_Query builder beats a bare get_terms() call
Term queries fail in ways that look like content problems. A category menu loses its top level because hide_empty counted only direct posts. include silently overrides the parent filter you also set. child_of returns nothing because the taxonomy is flat. None of these produce an error — they produce a list that is quietly wrong, which is exactly what this generator checks for.
The disappearing-parent bug, caught and fixed
hide_empty on a hierarchical taxonomy drops parent terms whose posts all live in children — the reason a category menu loses its top level. The generator warns on that exact combination and offers a one-click pad_counts, which rolls descendant counts into the parent.
parent and child_of kept apart
They do different jobs: parent returns direct children only, child_of returns the whole subtree at every depth. Setting both is flagged with a "Keep child_of" fix, and using child_of on a flat taxonomy is an error because it can only ever return nothing.
include and exclude take IDs, and it checks
A non-numeric value in either list is an error naming the offending entry and pointing you at the slug argument. Setting include alongside exclude or parent warns that include wins and the other filter does nothing at all.
fields => count validated against the rest
Asking for a count while number is set is a warning, because the limit caps the rows counted and makes the number wrong — with a one-click "Clear number". Ordering a count is flagged as pointless work.
Ordering checked for the arguments it needs
orderby => include without an include list is an error, and so is meta_value_num with no term meta clause to take the key from. Ordering by count ascending gets a nudge, since putting the emptiest terms first is rarely the intent, and term_order is flagged as meaningful mostly for WooCommerce attributes.
Term meta cache kept honest
Filtering on term meta while update_term_meta_cache is off is a warning, because every get_term_meta() call in your loop then goes back to the database one term at a time. One click restores the cache.
How does the term query generator work?
Say which terms, say how they should come back, and add term meta clauses only if you actually filter on them.
- 01
Choose which terms
Set the taxonomy, decide whether to hide empty terms, and pick a hierarchy filter —
parentfor direct children only, orchild_offor the whole subtree. Add a name search or an exact slug lookup. - 02
Include or exclude specific terms
Both take comma-separated term IDs. Switch exclusion to
exclude_treewhen you want a term and everything under it gone, not just the term itself. - 03
Set order and shape
Choose
orderbyand direction, cap the list withnumber, and pickfields— full objects,ids,names,slugs,id=>nameor a singlecount. Togglepad_countsand the term meta cache. - 04
Add term meta if needed, then export
Each clause takes a key, a comparison and a value. Clear the Checks tab, then take the class with its linked list, the filter dropdown, or the args array on its own.
Worked example — a category filter dropdown, ten busiest first
The ten categories with the most posts, excluding Uncategorized (term 1), with pad_counts on so a parent category reflects everything filed beneath it. This is the dropdown output mode, ready to drop into a filter form.
$terms = get_terms( array(
'taxonomy' => 'category',
'hide_empty' => true,
'exclude' => array( 1 ),
'orderby' => 'count',
'order' => 'DESC',
'number' => 10,
'pad_counts' => true,
) );
if ( ! is_wp_error( $terms ) && $terms ) {
echo '<select name="category">';
echo '<option value="">' . esc_html__( 'All', 'mytheme' ) . '</option>';
foreach ( $terms as $term ) {
printf(
'<option value="%1$s">%2$s (%3$s)</option>',
esc_attr( $term->slug ),
esc_html( $term->name ),
esc_html( number_format_i18n( $term->count ) )
);
}
echo '</select>';
}The is_wp_error() guard matters: get_terms() returns a WP_Error when the taxonomy does not exist, and iterating that object without checking is a fatal error rather than an empty list.
WP_Term_Query — frequently asked questions
The questions that come up when a term list is missing entries or ordered strangely.
What is the difference between get_terms() and WP_Term_Query?
get_terms() is a wrapper: since WordPress 4.6 it instantiates WP_Term_Query and returns the result. The practical differences are the return shape and the error path — get_terms() can return a WP_Error for an unknown taxonomy, so it needs an is_wp_error() guard, while the class returns an empty result. Since WordPress 4.5, get_terms() also takes the taxonomy inside the single arguments array rather than as a first parameter.
Why are my parent categories missing from get_terms()?
hide_empty defaults to true and compares against each term's own count, which only counts posts assigned directly to that term. A parent category whose posts all sit in subcategories has a count of zero and is dropped. Add 'pad_counts' => true, which rolls descendant counts up into each parent so the hierarchy survives.
What is the difference between parent and child_of?
parent matches terms whose immediate parent is the ID you give, so you get one level. child_of matches every descendant at any depth. parent => 0 is the way to fetch top-level terms only. Setting both is contradictory, and child_of on a non-hierarchical taxonomy returns nothing at all because there is no tree to walk.
Can I pass slugs to the include argument?
No — include and exclude accept term IDs only, and a slug in either list is silently discarded. Use the slug argument for slug matching (it accepts a string or an array), or resolve slugs to IDs with get_term_by() first. Note also that setting include makes exclude and parent inert; core applies include last and it wins.
How do I order terms by a custom term meta value?
Set orderby to meta_value_num (or meta_value for text) and supply a meta_key, which this generator takes from your first term meta clause. As with posts, the ordering JOIN excludes terms that have no value for that key, so terms missing the meta disappear from the list rather than sorting last.
How do I just count the terms in a taxonomy?
Set 'fields' => 'count' and the query returns a single integer instead of a list. Leave number unset — a limit caps the rows counted and makes the number wrong — and set orderby to none, since sorting a count achieves nothing. wp_count_terms() is the one-line alternative when you have no other filters.
Where do I paste the code from the WP_Term_Query generator?
You have three good options and one bad one. Best is a small site-specific plugin — the generator can output one for you, and it keeps working when you change theme. A code-snippets plugin is fine too. A child theme's functions.php works but ties the code to that theme. Never edit the parent theme: the next update overwrites it and your code is gone.
Can I use the generated code in client work or a commercial plugin?
Yes. The output is ordinary WordPress API calls that you configured — there is no licence attached to it and no attribution required. Use it in client sites, commercial plugins and themes, or products you sell. The generated file carries a short credit comment you are free to delete.
The other Query generators in the library, plus the WordPress tools most often used alongside this one.