How to List Categories in WordPress Using the Categories APIBy Jérémy Heleine
In a previous article we saw how to easily work with categories in WordPress. We covered how we can sort our posts into different categories, which can then be edited or deleted.
Having covered the basics, it’s now time to have a look at something that will be of more interest to developers: the Categories API, and how to retrieve and display category data.
Like the Links Manager API, the Categories API is a big topic, even bigger in terms of the number of functions available. In this article, we’ll be covering one function that is useful when we want to list our categories.
In the Links Manager API we find an important function that allows us to list our links. It’s no surprise therefore that we find the same thing in the Categories API:
wp_list_categories(), this is the function we’ll work with here.
Basically, you have to call this function in the place you want to see your categories listed.
As you can imagine, this result is entirely customizable. To mould it to our needs we can pass an argument to this function: an array containing values for the options we want to set. Let’s have a look at some of the available options.
Choosing the Categories to Display
Before seeing how to customize the output, we’ll begin with some options that allow us to choose what to display.
Include and Exclude Categories
First we find the option
include which accepts a list of category IDs to display. When you use this option,
wp_list_categories() will only display the categories with the IDs you passed it. You can indicate one or more IDs. If you want to indicate two or more IDs, you must separate these numbers with a comma.
$args = array( 'include' => '15,16,9' ); wp_list_categories($args);
If on the other hand you don’t want to choose what to display, but rather what not to display, the
exclude option is for you. It can be used exactly like
$args = array( 'exclude' => '15,16,9' );
Note that if you want to use the
include must be empty (its default value). Otherwise, the
include option wins and only the categories passed to it will be displayed.
Another option to exclude categories is
exclude_tree. Once again, it accepts a comma-separated list of categories’ IDs to exclude. The difference is that it will exclude the selected categories and all their children. Note that, to see this option working, you must set the option
0 (we will see below what this option does).
// 14 is the ID of "My life", parent of "My goldfish" and "My garden" which will also be hidden $args = array( 'exclude_tree' => '14', 'hierarchical' => 0 );
Ordering the Output
By default, categories are listed in alphabetical order. You can modify this behavior thanks to the
orderby option, which accepts a string. You can pick from the following options:
ID to order the categories by their ID (no, really?),
name to sort them alphabetically (the default value),
slug to sort them in the alphabetical order of their slugs, and
count to order by the number of posts they contain.
The chosen order can be reversed by setting
DESC (descending) as a value for the
order option (by default this option is set to
In the example below, we list the categories by the number of posts they contain: as the order is reversed, the category containing the greatest number of posts will be the first one to be displayed.
$args = array( 'orderby' => 'count', 'order' => 'DESC' );
Limit the Number of Displayed Categories
Once we have ordered our categories, we may want to limit the number of items listed. This can be achieved using the
number option. By default, this option is set to
null and there is no limit so all the categories are shown. By specifying a number, you can define the maximum number of categories to display. For example, we can list the five most used categories.
$args = array( 'orderby' => 'count', 'order' => 'DESC', 'number' => 5 );
This example lists the categories with the greatest number of posts. Another solution is to hide the unused categories. To do that we can use
hide_empty, a boolean set to
1 by default: empty categories are not shown. You can choose to display them by setting this to
// Show me all the categories, even the empty ones $args = array( 'hide_empty' => 0 );
Specifying Details to be Displayed
Details are important, and there are always some that we want to include.
For example you may want to display the number of posts contained in each category. To display this you can use the option
show_count and set it to
1. By default, this boolean is set to
0 and this count is not shown.
$args = array( 'show_count' => 1 );
Note that a post in a child category will also be added to the total number of posts of its parent. For example, the screenshot below is taken with three posts in the “My life” category: while there is only one post in this category, the two others are in the child categories.
You can modify this behavior thanks to the option
pad_counts. If you set this to
0, the parents’ counts will only display the number of posts in these parents’ categories and not include the posts in their child categories.
$args = array( 'show_count' => 1, 'pad_counts' => 0 );
Descriptions of the Categories
As we saw in our previous article, we can set a description for our categories. This description can be displayed with the option
use_desc_for_title. It’s a boolean set to
1 by default: descriptions are displayed in the
title attribute of the links in the list. If you don’t want to see this description you can set this to
$args = array( 'use_desc_for_title' => 1 );
Just as WordPress generates a feed for your posts, it also creates one for every category. Visitors can choose to only follow the updates of categories they are interested in, if they don’t like all of your content.
The links to these feeds can be shown in the list of our categories, thanks to the option
feed. By default this option is set to an empty string and links are not shown. The code below shows how to enable this option.
$args = array( 'feed' => 'RSS' );
By default, the linked feed is the RSS2 one. But WordPress can generate more feed types. If you prefer Atom for example, you can force WordPress to show this type of feed instead of the RSS2 one.
To select the type of feed you want to see displayed you can specify any of the following options :
$args = array( 'feed' => 'Atom', 'feed_type' => 'atom' );
Finally, if you prefer to use an image to link to your RSS feeds, you can indicate the URL of the image you want to see in the
feed_image option. The text in the
feed option will then become the alternative text for the image.
$args = array( 'feed' => 'RSS', 'feed_image' => 'http://website.org/my-awesome-rss-image.png' );
Is This Category the Current One?
If you use
wp_list_categories() on an archive page (in the
archive.php template), you can see that the current category (the one displayed by the archive page) is highlighted: the
li tag enclosing the link to this category has one more class than the other ones, named
current-cat. You don’t have to do anything to activate this behavior, and you can’t deactivate it (but you are free to not use it in your CSS!).
However, maybe it’s a behavior you want to see on more pages, like those which display a post. The good news is you can, thanks to the option
current_category. This boolean is set to
0 by default. By setting it to
1 the current category will be highlighted with the previously quoted class.
$args = array( 'current_category' => 1 );
For example, let’s assume that we display the list of our categories on the
single.php template. Then, with the previous array, the category of the current post is highlighted thanks to the class
current-cat. All we have to do now to display it is to add the appropriate CSS.
Showing the Hierarchy
If you have many categories, it’s a good idea to organise them into logical hierarchies, where we find parent categories and their children underneath them. There are a number of options for handling the display of hierarchies.
We’ll look at
hierarchical first. It’s a boolean set by default to
wp_list_categories() shows the hierarchy between the categories (with parents and children), exactly as in the screenshots since the beginning of this article. If you don’t want to show your hierarchy you can set it to
0: your categories will then be listed in one column without indenting the child categories.
Note the side effect of
hierarchical: if you choose to display the hierarchy, then the parents categories will always be shown, even if they are empty and the
hide_empty option is set to
// Don't show me the hierarchy $args = array( 'hierarchical' => 0 );
You can also use hierarchy to do other things like displaying the children of a given category using
child_of . We could describe it as the opposite of
exclude_tree: we give it the ID of a category and
wp_list_categories() will only display its children. However, the name of the parent category is not displayed.
// Show me all the children of this category $args = array( 'child_of' => 14 );
exclude_tree, we can only pass a single ID to
depth option allows you to control the number of levels which can be displayed in the list. It can be useful if you love categories and have a complex tree with a lot of generations. By default it is set to
0 and shows all the generations. The example below shows only two levels of categories: the parents and their first level children. If these children have their own child categories, they won’t be shown.
$args = array( 'depth' => 2 );
depth is linked to
hierarchical. In fact, if you set
0, giving a value to
depth will be useless: all the categories will be shown, regardless of their levels in the tree. On the contrary, you can also override the value of
depth in one case: you set
-1. The effect of this value is to display all the categories without any relation. All of the categories will be shown in one column, even if
hierarchical is set to
Controlling the Output
wp_list_categories() displays the list of our categories. If you don’t want that and prefer to store the result in a variable to display it later, you can set
$args = array( 'echo' => 0 ); $cats = wp_list_categories($args);
This can be useful if you want to modify the list before displaying it.
Next, let’s look at
show_option_none. By default, if
wp_list_categories() doesn’t find any category (it can happen if the other options are too restrictive for example), it displays the text “No categories“. You can change this to the text you want using this option.
$args = array( 'show_option_none' => 'Nothing found :(' );
title_li. In our tests, you may have noticed that the list of categories is encapsulated into an item of another list. This can be useful if you use
wp_list_categories() in a menu for example. Moreover, WordPress displays a title for this list, which is by default “Categories“.
You can modify this default title or even disable it by playing with
title_li. It accepts a string, which is the title to display. If you give this option an empty string, the list of categories won’t be encapsulated in another list at all.
$args = array( 'title_li' => 'My awesome categories' );
Be careful: if you disable the displaying of the list with an empty string you must enclose your list in
You don’t like lists? You will love the
style option: by default it is set to
wp_list_categories() displays categories as list items. If you set
none, your categories will be separated by
$args = array( 'style' => 'none' );
Finally, you can ask WordPress to display a link to all your categories thanks to the option
show_option_all. You give a string to this option, and WordPress will display a new link, pointing to all of your categories.
$args = array( 'show_option_all' => 'All categories' );
That’s it for
wp_list_categories(). The number of options available for this function is pretty big, as you can see.
Of course, the Categories API is not limited to this function. However, it is an important one: if you don’t have any specific need and just want a basic list of categories, don’t look for another function, this one is your simplest option!
Note that we didn’t talk in this article about
wp_dropdown_categories(). This function displays our categories into a dropdown HTML element. Like
wp_list_categories(), its output can be fully customized thanks to an array of options. These options are similar to those available with
wp_list_categories() , so we won’t describe them here. The only difficulty is that some options have other default values. To learn more about
wp_dropdown_categories(), you can go to the WordPress Codex.
But there are still other cases: what if we want to display our categories in a special way? In this case,
wp_list_categories() is not flexible enough, as we need to build our own DOM tree. That’s why, in the next article, we’ll have a look at some other useful functions in the Categories API.