How to customize wp_list_categories HTML output

Over the last year, I have been doing few little updates & upgrades to my personal site. We all get busy with work and life in general, and I am no different. I figured that my personal site is a perfect place to practice and getting better at my craft without any limitations. I do have to admit that I cut corners here and there when I got stuck with figuring few things up, especially when faced with more advanced PHP skills. One of those was trying to customize HTML output of my categories list.

I fell in love with Symbolset and their amazing gallery of font icons. The idea of not having to deal with images or svg sounded ideal to me, so for obvious reasons I couldn’t wait to start using them. Implementation was super easy, especially for something like my global footer where I am using icons for links to some of my social media accounts. The concept is easy and pretty straight forward. There are few ways how you can get your desired result. I found preference in being able to utilize actual meaningful labels to generate my icons. So for instance, to display an Instagram icon Instagram, all I needed to do was the following:

<a href="" class="ss-icon ss-social-regular">Instagram</a>

Where I got stuck was when trying to incorporate the same concept for my post’s categories. First, I had to figure out how categories in WordPress are set up and generates its markup dynamically. I knew that when creating a new category in WordPress, you have few fields to fill out including name, description and slug. This got me started on thinking how I can utilize them appropriately to do most of what I needed for me by filling them up in such way, that it’s output would make sense to anyone. So my description and slug are identical, only name differs in few cases depending on word choices I have to work with each icon of my choice. For example, in order to show icon for my “Podcast” category, I am using “mic” in its field name.

When I first implemented this approach few months ago, I just manually typed out all the categories with all its necessary markup. I just couldn’t figure out quickly how to customize HTML output for wp_list_categories in PHP, so that was my quick fix. However, it’s been on my mind, so whenever I had some time, I played around with it. I’ve gone through number of trials and errors based on what other people on web have been doing but Stackoverflow has came to rescue once again and got me closer to what I was looking for. This got me the HTML output I was looking for since the beginning.

<ul class="list-items categories">
     <?php $category_ids = get_all_category_ids(); ?>
	  $args = array(
	     'orderby' => 'slug',
	     'parent' => 0
	  $categories = get_categories( $args );
	  foreach ( $categories as $category ) {
	     echo '<li><a href="' . get_category_link( $category->term_id ) . '" rel="bookmark"><i class="ss-icon" aria-hidden="true">' . $category->name . '</i>' . '' . $category->description . '</a></li>';

Recently, the smart folks at Filamentgroup have written about about how to implement Bulletproof Accessible Icon Fonts on your site, which I would recommend to read, as it’s very resourceful with some great tips and options you may have.


  1. Kia Shine says:

    This doesn’t work for hierarchy of categories

  1. Required
  2. Required, but never shared