WP_Term_Query Generator
Build a WP_Term_Query or get_terms() call: taxonomy, hierarchy, empty terms, ordering, meta conditions and the fields you actually need.
<?php
/**
* Terms from the category taxonomy.
*/
$args = array(
'taxonomy' => 'category',
'hide_empty' => true,
'orderby' => 'name',
'order' => 'ASC',
);
$terms = get_terms( $args );
// get_terms() returns a WP_Error for an unregistered taxonomy, not an array.
if ( is_wp_error( $terms ) || ! $terms ) {
return;
}
foreach ( $terms as $term ) {
printf(
'<a href="%1$s">%2$s</a>',
esc_url( get_term_link( $term ) ),
esc_html( $term->name )
);
}
Output is valid and updates as you type.
Fix the highlighted fields to update the output.
Build the arguments for get_terms() or WP_Term_Query, including the two settings that explain most “my term is missing” reports: hide_empty and the hierarchy.
How to use
- Turn
hide_emptyoff while you are building. It defaults to true, so a term with no posts yet is simply not returned. - Choose the hierarchy deliberately.
parentis one level down;child_ofwalks the whole subtree. - Ask for
idsornameswhen that is all you need. Each full term is an object with its own meta lookup. - Set a number on a taxonomy that grows, such as tags. Zero means every term, and a tag cloud of 4,000 items is a slow page.
- Handle the
WP_Error.get_terms()returns one for a taxonomy that is not registered, which is a different shape from an empty array.
Example
Top level categories that have posts, ordered by how many:
$args = array(
'taxonomy' => 'category',
'hide_empty' => true,
'parent' => 0,
'orderby' => 'count',
'order' => 'DESC',
);
$terms = get_terms( $args );
if ( is_wp_error( $terms ) || ! $terms ) {
return;
}parent => 0 is top level only. Leaving it out returns children mixed in with their parents, in name order, which reads as a broken list.
Pitfalls
hide_emptyis true by default. A newly created term, or one only used by drafts, does not appear.- The count behind
hide_emptyis the published count for the taxonomy’s object types. A term used only on private posts counts as empty. parentandchild_ofare different: one level versus the whole subtree. Passing both is contradictory.get_terms()returnsWP_Errorfor an unregistered taxonomy.foreachover that is a fatal.numberwithoffsetpaginates, but the hierarchy arguments are applied after the limit in some cases, which gives odd results on deep trees.orderby => countsorts by the cached count, which can lag after a bulk import until the counts are recalculated.- Term meta needs WordPress 4.4. On older sites
meta_keyhere does nothing at all. get_terms()results are cached, and the cache key includes every argument. Passing a changing value, such as a timestamp, defeats it.
Compatibility
get_terms() has been in WordPress since 2.3, and since 4.5 it takes a single arguments array with taxonomy inside it. WP_Term_Query arrived in 4.6, term meta in 4.4, and wp_dropdown_categories() accepts the same arguments plus its own display ones. The generated code targets PHP 7.0 and up, and the tool runs entirely in your browser.
Frequently asked questions
Why is my new term missing?
hide_empty is on and nothing published uses the term yet. Set it to false.parent or child_of?
parent for one level, child_of for the whole subtree beneath a term.How do I get terms for one post?
wp_get_post_terms() or get_the_terms(). This query is for the taxonomy as a whole.Why is get_terms() returning an error?
init or later, after the taxonomy exists.