Create a page template to show a taxonomy list.

Create a page template to show a taxonomy list.

Custom Taxonomy List Page
(click to embiggen)

WordPress gives us categories, and we can create custom taxonomies, but this week I discovered that there is nowhere on your average WordPress site where you can actually list your categories, unless it’s an archive page or a 404 page. It isn’t something I’ve ever needed yet, and according to my searching, that’s true for most everyone (a lot of fruitless searching), but hopefully there is at least one person out there who wants to know how to do this, because I figured it out–here’s how to make a custom page template to list your categories or other taxonomies.

I’m building a website with a custom post type with several taxonomies. I needed to create couple pages which would show each taxonomy as a list. The Codex showed me how I could PHP my way into it, but it necessitated hard coding in the taxonomy name, which doesn’t help me, as I would really like to have this available for multiple taxonomies.

This tutorial works for the Genesis Framework by StudioPress (this is a referral link).

Genesis comes with a blog page template built in, and you can use it to create blog type pages for categories (and post types and pages) by adding a custom field with a name of query_args and a value of cat=3, where 3 is the ID of your category. You can modify the field further with all kinds of arguments, like:


So your blog template will show your portfolio custom post type, sorted alphabetically.

My thought was to use something similar for the category lists, but it took some digging. In the Codex, I found the page on get_terms (see the custom taxonomy example), which pointed me in the right direction–I just needed to set it up to be configurable from the front end.

The key was to set up my template and custom fields to separate the taxonomy from the arguments. Entering a taxonomy custom field is required; the arguments are not, unless you want your taxonomy list to be in a certain order. Here’s the template:

[gist id=”7028494″]

Name the template page_taxonomy.php (or whatever you want to call it), upload it to your theme file, and voila! You’ll have a new template to choose from when you create a page.

Create your page, name it whatever you want, call it whatever you want (you can set the permalink to be /category, actually, as that throws a 404, so I used my taxonomy), add in content (it will show above your list of terms), set the page template, and then add your custom fields. You must enter a field named taxonomy and the value will be your taxonomy–for example, category. Entering arguments for order or anything is optional.

You could trick this out more, either in the template or CSS–the template at this point is just a simple list, with each li set at 50% and floated left, but the hard work of setting it up is done.

If you find this useful, I’d love to see what you do with it!

Reader Interactions


  1. Janeth says

    Hello Robin,

    Thanks for the article, I was looking for something like this.
    I was wondering, do you know why I might be getting this error:

    Catchable fatal error: Object of class WP_Error could not be converted to string in taxonomy-accommodations.php I am getting it when enabling my taxonomy custom template.

    I would appreciate any help on this.


    • Robin says

      Janeth, my guess is that you haven’t added your taxonomy as a custom field, which is required–if there is no custom field with a name of taxonomy and a valid entry for value, you’ll get that error.

      There is probably a way to tighten up this code so that the page will function on a generic level if no custom field is added, but I haven’t dug that far yet to do so. At this point, if there is no taxonomy field, the page does break.

    • Robin says

      Janeth, did a bit more digging and have revised the template to show a list of the post categories if no taxonomy custom field is set.

      • Janeth says

        Hi Robin, Thank you very much for taking the time to answer my question. You were totally right, it seems I was not setting correctly my taxonomy custom field set. Now I can see my custom taxonomy list on my page.

        Can I ask you one more question? I added your code on taxonomy-places.php, do you know if I can add the list of all my custom type fields that belongs to each custom taxonomy on the same template? For example if I click on PLAY taxonomy it would display all my custom post types on that same page… thank you very much,


        • Robin says

          Janeth, I’m not 100% sure what you are wanting to do. If you want multiple pages which could show these lists, the easiest way to do so, I think, is to use this as you would any other template–mine, for example, is set up exactly as posted and saved in the theme file as page_taxonomy.php. I can create any page, use this template, and add the custom field for the specific taxonomy and it’s good to go, no extra work. Does that make sense? The php is a one-time job, but the template itself can be reused multiple times, much like the Genesis blog template.

          • Janeth says

            Hi Robin, thank you for your reply,

            What I am trying to do is something like this:
            Say that each tab is a custom taxonomy which displays its correspondent custom post types and fields…

            I think I did not undesrtand your explanation. instead of adding your code to taxonomies-custompost.php I should use custompost.php?

            thanks Robin!

          • Robin says

            Janeth, I’m not sure–you may be beyond using a template and may need to hard code this in, probably with a way to rewind and repeat the loop somehow. I’m afraid it’s beyond me at this point. Good luck!

  2. William says

    I am having an issue with only getting a 404 page or a page that dose not display anything depending on the url. I have added all the custom fields to the corresponding page. Any toughs?

    • Robin says

      If you’ve set the url slug to be category, you will get a 404. If the template doesn’t display anything, my guess would be that your custom field(s) may not be correct. If you remove the custom fields, the template should show all of your categories by default. I’d try that to see if it works–it does for me here. If that works, then double check that your taxonomy in your custom field is correct.

      • William says

        When I changed the url slug I am now getting a blank page (the site header and footer loaded but nothing else). I removed all the custom fields and only added back the custom filed (taxonomy = series) on the page. Any other thoughts? What am I missing?

        • Robin says

          If you remove that custom field as well, do you get a list of all of your categories? If so, my guess is that your custom field is incorrect. If series is a valid taxonomy, make sure that your custom field Name is simply taxonomy, and the Value is series. There isn’t going to be an = in there anywhere. If your custom field looks correct, then my guess is that the taxonomy is really something other than series (you need the actual name of the taxonomy, which can be different from the labels WordPress uses).

          • William says

            I have double checked the taxonomy name and it’s definitely series. I tried removing all custom fields from the page and am getting the same results. Here is a link to the site: [link redacted]

            Do I need to change anything in the php template your provided above or can I just copy and paste it exactly how you provided it?

          • Robin says

            The template works for me with no changes. I would double check that you’ve got everything copied over exactly, but there may be something else going on, since none of the page markup is being output at all–the template should only modify the entry content. Do you have a working link for a series archive? Because the only way I get similar output is if I put in a made up taxonomy name, at which point I get errors.

  3. William says

    Here is the link for a working series archive: [link redacted]

    • Robin says

      From what I can see here, that seems like it should work, but it’s hard to tell from the front end. If you want to use my contact form and send me an email with admin access information, I can take a look, if you like. How is the taxonomy/post type being created? That may be another clue.

    • Robin says

      I’ve also just updated the template so that if an error is the result of getting the taxonomy, you’ll get the “No taxonomy custom field was created.” message instead of just nothing.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.