WordPress get_terms Example: Fetch Taxonomy Terms Efficiently

Last reviewed: April 26, 2026

Taxonomy-driven sites depend on term queries for filters, directory pages, topic navigation, and editorial indexes. The common mistake is calling get_terms() with loose defaults, then assuming the result shape, count behavior, and empty-term handling will always match the front-end design.

This guide shows a predictable get_terms() pattern for fetching terms efficiently and defensively in themes and plugins.

Request only the taxonomy you need

<?php
$terms = get_terms(
	array(
		'taxonomy'   => 'category',
		'hide_empty' => true,
		'orderby'    => 'name',
		'order'      => 'ASC',
	)
);

Always set the taxonomy explicitly. Relying on broad defaults makes the query harder to reason about and easier to break when the code evolves.

Handle WP_Error before rendering

if ( is_wp_error( $terms ) ) {
	error_log( 'Term query failed: ' . $terms->get_error_message() );
	return;
}

if ( empty( $terms ) ) {
	return;
}

An invalid taxonomy or unsupported argument combination can return WP_Error. Do not jump straight into a foreach loop.

Render a small term navigation list

echo '<ul class=\"topic-list\">';

foreach ( $terms as $term ) {
	echo '<li><a href=\"' . esc_url( get_term_link( $term ) ) . '\">' . esc_html( $term->name ) . '</a></li>';
}

echo '</ul>';

Escape both the term name and the generated link. Term data is usually trusted less than developers assume because editors and imports can modify it.

Use fields and counts deliberately

If a template only needs IDs, slugs, or names, narrow the return shape with the fields argument. If a filter UI should show only non-empty terms, keep hide_empty enabled unless there is a clear product reason not to.

$term_ids = get_terms(
	array(
		'taxonomy'   => 'category',
		'hide_empty' => false,
		'fields'     => 'ids',
	)
);

Production checklist

• Set the taxonomy explicitly.
• Check for WP_Error and empty results.
• Escape term names and links when rendering.
• Use hide_empty intentionally.
• Narrow the fields output when the template does not need full term objects.
• Keep large taxonomy UIs paginated or cached when the term count grows.

Common mistakes

• Skipping error handling. Invalid taxonomies do happen in real plugin code.
• Rendering empty term lists. The UI should handle the zero-result case cleanly.
• Using full objects when only IDs are needed. That adds unnecessary overhead and ambiguity.
• Assuming empty terms are always irrelevant. Some editorial workflows want to expose future taxonomy buckets intentionally.
• Printing raw term names into HTML. Output still needs escaping.

Related reading

If you are defining the taxonomy yourself, pair this with the custom taxonomy guide. If a front-end archive layout depends on the result, combine it with the template hierarchy article.

References and further reading

• WordPress Code Reference: get_terms()
• WordPress Code Reference: WP_Term_Query::get_terms()
• WordPress Code Reference: get_term_link()