WordPress wp_list_categories Example: Render Category Navigation Cleanly

Last reviewed: May 3, 2026

Category navigation still matters on content-heavy WordPress sites, but many themes either hardcode term links or build overly custom loops for simple sidebar navigation. wp_list_categories() is the core helper for rendering category lists with predictable markup and argument-based control.

This guide shows how to use wp_list_categories() cleanly and when to return the HTML as a string for tighter layout control.

Render a category list with explicit arguments

<?php
wp_list_categories(
	array(
		'title_li'   => '',
		'hide_empty' => true,
		'show_count' => true,
	)
);

This is usually enough for a sidebar taxonomy navigation block without building a manual term loop.

Return the markup when the layout needs wrapping

$categories = wp_list_categories(
	array(
		'title_li' => '',
		'echo'     => false,
	)
);

if ( $categories ) {
	echo '<nav class=\"category-nav\"><ul>' . $categories . '</ul></nav>';
}

echo => false is the clean path when the theme needs wrapper markup but still wants WordPress to generate the list items.

Choose hide_empty intentionally

Editorial sites often want only live categories with content, while staging or setup utilities may need to show empty terms too. That argument should reflect the real use case, not a copied default.

Use the helper for category list output, not for generic taxonomy logic

If the UI needs custom grouping, cross-taxonomy relationships, or non-category navigation, a term query may be more appropriate than forcing everything through one rendering helper.

Production checklist

• Pass explicit arguments for empty terms, counts, and hierarchy behavior.
• Use echo => false when wrappers belong to the theme layout.
• Keep title_li intentional so list semantics stay clean.
• Use the helper for category output, not generic taxonomy modeling.
• Test empty, nested, and high-volume category sets.
• Review mobile layouts where long taxonomy lists can become heavy.

Common mistakes

• Hardcoding category links. Taxonomy navigation should follow real term data.
• Ignoring hide_empty. Empty-term behavior affects both UX and QA.
• Forcing complex taxonomy logic into one list helper. Different problems need different APIs.
• Letting wrapper markup leak into the helper arguments. Theme layout should stay separate.
• Skipping high-volume layout tests. Category lists can grow longer than expected.

Related reading

If the site needs a broader taxonomy fetch beyond category rendering, pair this with the get_terms guide. If the visible category list should match term badges on article cards, continue with the get_the_terms article.

References and further reading

• WordPress Code Reference: wp_list_categories()
• WordPress Code Reference: get_categories()
• WordPress Code Reference: get_term_link()