7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. WordPress

Taxonomy Archives: List Posts by Taxonomy's Terms

Scroll to top
Read Time: 8 mins
Final product imageFinal product imageFinal product image
What You'll Be Creating

By default, WordPress creates archives which list all of your posts in reverse order. If users are looking for posts in a certain category or with a given taxonomy term, they'll have to visit the archive page for that category or term.

But what if you want to make your main archive for a post type more user-friendly? In this tutorial, I'll show you how to create an archive page for a custom post type which displays posts of that post type categorized according to a taxonomy, so that instead of one long list visitors will see a list for each taxonomy term.

What You'll Need

To follow this tutorial you'll need a development installation of WordPress and a code editor. You'll be creating a theme which is a child theme of twentyfourteen, so you'll need that installed (which it should be by default).

I'm not going to show you how to create a child theme, but if you're stuck, just have a look at the stylesheet in the code bundle for this tutorial.

1. Getting Started: Registering the Post Type and Taxonomy

In my experience this technique is most commonly needed for custom post types and taxonomies rather than for normal posts and categories or tags, so I'll start by registering a post type and taxonomy.

Note: I'm using the same 'animal' post type that I registered in an earlier tutorial on creating an image-based archive. If you want to push things a bit further, you could combine the technique in that tutorial with the one I'm showing you here and display your taxonomy term lists with featured images.

In your theme's functions file, add the following code to register the post type:

Next, add the code to register the taxonomy:

Once you've done this, add some data. Below you can see the data I've added with some taxonomy terms applied. I don't make any claim for the accuracy of my terminology with regard to animal families, so please don't comment if I've got that wrong!

2. Setting Up the Archive Template

The next step is to create an archive template for the new post type. In your theme, create a new file called archive-animal.php.

As this theme is a child theme of twentyfourteen, the archive template will need code copied from that theme as a wrapper for the custom loop you're going to create. So add the following to your archive template:

Note: If you're working with your own theme, copy the wrapping code from your own theme's index or archive file.

3. Populating the Archive Template: Fetching Taxonomy Terms

So that your archive can display animals by taxonomy term, the next step is to fetch those terms.

In your new template file, below the closing </header> tag (or below the opening part of your wrapping code if you're using your own theme), fetch the terms using get_terms():

Note that I've used two parameters here:

  • orderby - this allows you to specify the order of the terms displayed. I've used count as the value so that the term with the most posts assigned to it will be displayed first, but you could order by name or  ID - if you leave this blank, WordPress will order by name. See the Codex page on get_terms() for more details.
  • hide_empty - this tells WordPress not to fetch any terms without posts assigned to them. It saves you having to check if your query has any posts later on.

4. Populating the Archive Template: Defining the Query

Having done this, you use foreach() to tell WordPress to pass through each of these terms and run a query which you need to define. Below the code you just added, insert the following:

This tells WordPress to run through each term, and then defines the query it has to run each time. The arguments for the query include the post type and the term in the 'animal_cat' taxonomy, which is the value of the $term variable.

5. Populating the Archive Template: Adding a Loop

Having defined your query, you need to add a loop. First, output the name of the term being queried as a heading. Below the line beginning $query but inside the braces of the foreach statement, add this line:

Next, add the code to contain your posts in a list:

Inside the list, now add your loop:

As you can see , this is a straightforward loop which outputs the title of each post inside a link to the post, and doesn't output any content. If you wanted you could add an excerpt or featured image here.

Finally, reset the query using wp_reset_postdata() below the line reading echo '</ul>';

The Whole Loop

This is what your query and loop will now look like:

Finally, save your template file and view your post type archive. You'll see that it lists your posts by taxonomy term rather than in one long list.


This technique is useful when you want visitors to be able to quickly see categorised data without having to look at a range of archive pages - it brings it all together in one place but sorted for convenience. Here are some ideas for how you could adapt the technique and take it further:

  • Call categories or tags instead of terms. To do this, you would use get_categories() or get_tags() .
  • Instead of creating a custom archive for a post type, use this technique in your index.php file to display posts by category, tag or taxonomy terms.
  • Instead of running one loop for each term, run two: the first one can display the most recent post with that term in full and the second one can display a list of all the rest of the posts. Use posts_per_page and offset in your query arguments to do this - see details of how this work on the WP_Query Codex page.
  • Use posts_per_page to limit the number of posts displayed so that each list is the same length. You could combine this with styling to display lists side by side.
  • For each term, add a link to the term archive page after the list of posts - this is particularly useful if you're not displaying all of the posts in your list. Use get_term_link() to do this.
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.