About wp_list_categories() function

wp_list_categories() is a built-in WordPress function that displays a list of categories associated with posts in your site. It is commonly used in theme templates, sidebars, or anywhere you want to show a categorized list of posts for easier navigation and better content organization.

What Does wp_list_categories() Do?

This function outputs an HTML list (<ul> by default) of your WordPress categories. Each category name is linked to its archive page, where users can view posts filed under that category.

Basic Usage

By default, calling the function with no parameters lists all categories:

<?php wp_list_categories(); ?>

This will generate something like:

<ul class="categories">
<li class="cat-item cat-item-1"><a href="https://example.com/category/news">News</a></li>
<li class="cat-item cat-item-2"><a href="https://example.com/category/events">Events</a></li>
<li class="cat-item cat-item-3"><a href="https://example.com/category/tutorials">Tutorials</a></li>
</ul>

Common Parameters

You can customize the output by passing an array of arguments to the function:

Parameter Description Example
show_count Display the number of posts in each category. (true/false) 'show_count' => true
title_li The title to display for the list; defaults to “Categories.” To omit title, set to empty. 'title_li' => ''
orderby How to sort the categories (e.g., ‘name’, ‘count’, ‘ID’, ‘slug’). 'orderby' => 'count'
order Sort order, either ‘ASC’ or ‘DESC’. 'order' => 'DESC'
exclude Category IDs to exclude from the list. 'exclude' => '1,5'
include Category IDs to include. 'include' => '2,3,7'
hierarchical Display categories in a nested (parent-child) hierarchy. (true/false) 'hierarchical' => true
hide_empty Whether to hide categories with no posts. (true/false) 'hide_empty' => true
depth How many levels of hierarchy to display. 0 means unlimited. 'depth' => 2
class CSS class to apply to the <ul> container. 'class' => 'my-category-list'

Example: Customized Category List

<?php
wp_list_categories( array(
'show_count' => true,
'title_li' => '',
'orderby' => 'name',
'order' => 'ASC',
'exclude' => '10',
'hierarchical' => true,
'hide_empty' => true,
'class' => 'custom-cat-list'
) );
?>

This outputs an alphabetical list of categories (excluding category ID 10), showing post counts, hiding empty categories, and applying a custom CSS class.

Use Cases

  • Displaying categories in sidebar widgets or navigation menus.

  • Creating category-based archives or filters for posts.

  • Enhancing user navigation and content discoverability.

Notes

  • The output is wrapped in a <ul> list by default.

  • You can customize the HTML structure further by using filters like wp_list_categories or by building your own category list if needed.

  • For showing categories with checkboxes or dropdowns, WordPress provides other functions like wp_dropdown_categories().

FAQs

What does the wp_list_categories() function do?
wp_list_categories() generates an HTML list of WordPress categories with links to their archive pages. It helps display category navigation menus or sidebars for visitors to browse posts by category.

How can I show the number of posts next to each category?
Use the 'show_count' => true argument when calling wp_list_categories(). This appends the post count next to each category name in parentheses.

Can I exclude certain categories from the list?
Yes, by using the 'exclude' parameter and passing category IDs you want to omit, e.g., 'exclude' => '4,7'.

Is it possible to display categories hierarchically?
Yes, set 'hierarchical' => true to show parent and child categories nested within the list.

How do I remove the default “Categories” title above the list?
Set 'title_li' => '' to remove the default title, especially useful when using this function inside your sidebar or widget areas.

Can I customize the CSS class applied to the category list?
Yes, use the 'class' parameter to assign a custom CSS class to the <ul> element wrapping the categories.

What happens if I set 'hide_empty' => true?
Categories without any posts will be hidden from the list, ensuring only active categories are shown.