Codeable info

How to use Custom Taxonomies in WordPress

Posted on by in WordPress Tutorials

This is an advanced WordPress tutorial on how to use custom taxonomies to better categorize and distribute content throughout a WordPress blog or website. If you are not sure what taxonomies are or don’t know how to use the three default taxonomies in WordPress, then be sure to read my first tutorial on “Understanding Taxonomies in WordPress”. That is a must before attempting this more advanced tutorial on custom taxonomies for those of you who have any doubt about the subject.


Before attempting this tutorial you should have at least some understanding of the following prerequisites:

  • PHP – You will need to edit some WordPress PHP files in order to use custom taxonomies.
  • HTML – At minimum, you should know basic HTML tags and understand structure to be able to create your own markup when needed.
  • Taxonomies – You need to at least know what they are and how they can help you organize your WordPress blog or website. If you don’t have this basic knowledge already, read my first tutorial on taxonomies referenced in the first paragraph of this tutorial.
  • WordPress – You need to have a fairly well understanding of the inner workings of WordPress since this is one of my more advanced tutorials. You need to at least know how to move about in the file system and where to find theme files and key files in WordPress for making custom changes.

Why Use Custom Taxonomies?

Imagine a case where you have a fairly large WordPress blog or website and you need to divide up your content into more categories than the default taxonomies allow for. What do you do? Well, that is the purpose of this tutorial on custom taxonomies. You will need to have more categories and sub categories to separate your content and organize it in a manner that makes the content easy for your readers to view. Not only will readers be able to view content in the way WordPress intended, in a chronological order, but they will also be able to view globs of similar content to the article they just read by clicking on one of the tags presented in the article. Such tags can be added with the help of custom taxonomies. Of course some tags are also possible with default taxonomies, but if you are reading this tutorial, I am assuming that the default ones are not enough for you. Thanks to the custom taxonomy API added since WordPress 2.3, custom taxonomies are now possible for everyone and they are not too difficult to use once you get the hang of them.

Down and Dirty with Custom Taxonomies

Okay for those of you that really want to move forward and learn to make your own plugin or just want to add new taxonomies the down and dirty way, here is how you can do it. The first step will involve the register_taxonomy built in core WordPress function that links into the taxonomy API for WordPress. Next we will start off with the register_taxonomy function and then we go on to show you some actual usage cases for your convenience.

Using the register_taxonomy Function

Here is how to use the register taxonomy function which goes in the functions.php file for the theme you are using currently in WordPress. If you are creating your own plugin, you can put it in a plugin file instead, but either way the context is the same, like this:

<?php register_taxonomy($taxonomy, $object_type, $args); ?>

Parameters of the register_taxonomy Function

As you can see from the above usage example, the register_taxonomy function takes three parameters which are explained below:

Taxonomy – is a required name parameter which cannot contain any caps or spaces, just like a slug. Also, it has to be no more than 32 characters long because of the database restriction on it. This is what you use to give your taxonomy a name you can recognize.

Object_type – is another required parameter that names the object type of the taxonomy object. Basically, this is tells WordPress what object the taxonomy is for. It could be for any registered custom post type that you may have created or more commonly it can be for any of the following built in objects:

  • post
  • page
  • attachment
  • revision
  • nav_menu_item

More than likely you will be dealing with mostly post types and possibly some of you may use the page type as well, but the others are there if you need them. Once you get more into using custom taxonomies, you are likely to use all five sooner or later. For the time being we are going to study just how they work for posts since that is the most common usage scenario and most likely what you are here to learn about.

Args – is an optional parameter consisting of an array of arguments. The default is none. Just to demonstrate how this is used, here is an example:

register_taxonomy( 'food', 'post', array( 'hierarchical' => false, 'label' => 'Places', 'query_var' => true, 'rewrite' => true)

That is just a simple example that uses three of the common arguments available. Hierarchical is the argument that lets WordPress know whether to treat the new taxonomy like a tag or like a category. Hierarchical is set to false by default and should be set to true if you want to use it like categories. Label, the next argument used above if for the plural version of the taxonomy name for translation purposes. Query_variable, the next one, is set to the taxonomy name in the by default and can be set to any text instead or to false to disable it. Rewrite, the last argument used in the above…

That wraps up the register_taxonomy function fairly well for the purposes of this tutorial. If you need to learn more about it, look it up in the WordPress codex online and you will find the official page on it. For what we aim to do in this tutorial however, that is more than you need to know. Next we will look into making a practical usage case of adding taxonomies to a WordPress blog and then calling them into use in the WordPress loop.

Practical Usage of Custom Taxonomies

Below I will show you how you can use custom taxonomies in your blog or website in a couple of different ways. First I will cover how to use the register_taxonomy function mentioned above in an actual usage scenario. First, I want to show you what the results will be if you call the register_taxonomy function from your theme’s functions.php file. Here is what it will add to the WordPress dashboard in the right column underneath where the admin box for tags and categories are:


The above image is what we will show you how to add to your WordPress admin to control the new custom taxonomy we will be adding to your WordPress site or blog. Here is how I added the above “Foods” Taxonomy to my test site:

Find your functions.php file for the active theme you are currently using. It should be in the folder wp-content/themes/your-theme where “your-theme” is the one you have active. Open the file in your favorite text editor or open it from the WordPress admin by going to “Appearance”/”editor” and finding the functions.php file in the right column. Then click on it to open it in the WordPress file editor.

Add the following to the functions.php file where you can find it easily. I like to make a comment line before adding anything so I know why I added it later. Here is the code I added to my functions.php file to add the box in the above image to my WordPress admin:

add_action( 'init', 'create_food_taxonomy', 0 );
function create_food_taxonomy() {
 register_taxonomy( 'food', 'post', array( 'label' => 'Foods' ) );

The above code is slightly different than the first example above where I explained the register_taxonomy function in the first place because we don’t need all the arguments this time. The defaults for most of the arguments are fine for what we want to do which is simply add a taxonomy and display what taxonomies we added at the end of the posts we added them to. This will also work to display only posts with the specified taxonomies which is what you need to do to categorize posts with custom taxonomies. Next we will look at how to achieve both examples just mentioned.

Now to show you that the new taxonomies do exist, you first will need to add some terms to the Foods taxonomy we just created for any blog posts in which you care to use the new taxonomy. Open up a post or create one that you want to use the Foods taxonomy with and add a couple Food categories such as chicken, beef, pasta or whatever fits for your taxonomy if you didn’t use Foods as I have in my example. Add at least two taxonomy terms for at least two posts to see how they work. You add them just by typing them into the box like the above image illustrates. Then click on the “Add” button after each. You can also enter them as a comma separated list and then click the “Add” button. When you are done, click the update button for the post just to be sure everything saves as it should.

Now that you have a taxonomy created and have used it for at least a couple posts, it’s time to see it in action! First, try displaying the taxonomies at the end of each post they are tied to. You can do this by adding the following code to the loop that calls your posts. So you would be adding it to index.php in most themes or if you are using Eclipse, it would be in core/post-actions.php, but most themes will have the loop in the index.php file. Here is what you want to add to the end of the loop somewhere before the endif statement:

<!--Ians custom taxonomy cloud here:-->
<?php echo get_the_term_list( $post->ID, 'food', 'Foods: ', ', ', '' ); ?

After adding the above comment (or similar comment) and line of code to your index.php or other file that contains your theme’s WordPress loop, you should be able to view a post that you added the taxonomies to and it will display them just like at the bottom of the image of one of my blog posts where I tested the code as you see here:

taxonomy example

See where it says “Foods: beef, chicken”? In the above example, beef and chicken are the taxonomy terms I added to the test custom taxonomy post. Clicking on either of the terms will now take you to a list of other posts that have been tagged with the same terms. Pretty neat huh?

Using Custom Taxonomies to Display a Custom Category of Posts

I already showed you how to make a tag cloud with custom taxonomies. Now I will show you how to make pages with just posts containing the specified taxonomy terms created with that same taxonomy we just created. There is no need to add another custom taxonomy to your functions.php file for this exercise. Just use the one from the last exercise. Be sure you have at least two posts that use the same taxonomy terms before you continue. Then all you have to do to see how this feature works is click on the terms in the post (like chicken and beef in the above image) and it should take you to new page with all the posts that have been tagged with the same terms or tags. For example, clicking on chicken in the above example image would take you to a page of all posts that have been also tagged with the term chicken.


Whew, you might be glad this tutorial is over with. I know it wasn’t that difficult, but there is a lot to learn with taxonomies and they can be confusing. I just hope this primer gets you off to a good start. I made this tutorial rather easy so you wouldn’t get lost because many of the tutorials I found online were way too complex for beginners and I wanted this one to be more user-friendly for folks that are not so accustomed to taxonomies and customizing WordPress inner files. I hope it did you justice. You can always refer to the WordPress codex to learn more. Learning is fun! Keep telling yourself that!

Comments Closed

Codeable info