How to Create and Query Custom Taxonomies in WordPress

WordPress is not just a blogging platform; it is a powerful content management system (CMS) that allows users to categorize and organize content effectively. One of the key features that facilitate this organization is taxonomies.

This post covers what taxonomies are, their types, how to create and manage them, and provides code examples to help you understand their implementation.

What are Taxonomies?

In WordPress, a taxonomy is a way to group posts and custom post types together. It allows you to define relationships between different pieces of content, making it easier for users to navigate your site.

For instance, if you have a blog about cooking, you might categorize your posts into different taxonomies like “Cuisine” (Italian, Mexican, etc.) or “Meal Type” (Breakfast, Lunch, Dinner).

WordPress comes with two built-in taxonomies:

• Categories: These are hierarchical and allow for subcategories.
• Tags: These are non-hierarchical and are used to describe specific details of your posts.

When you create a new category or tag in WordPress, you are actually creating a term inside a taxonomy.

Understanding this distinction is important – categories and tags are the taxonomies themselves, while the individual items within them (e.g., “Desserts” or “chocolate”) are the terms.

In addition to these default taxonomies, WordPress allows developers to create custom taxonomies tailored to their specific needs.

Types of Taxonomies

Understanding the different types of taxonomies available in WordPress is crucial for effectively organizing your content and enhancing user navigation.

1. Built-in Taxonomies

As mentioned above, WordPress has two built-in taxonomies:

• Categories: Use categories to group posts. They are hierarchical, meaning you can have parent and child categories. For example, a “Desserts” category can have subcategories like “Cakes” and “Ice Cream.”
• Tags: Tags are more specific and are used to describe particular details of a post. They are not hierarchical. For example, in a post about chocolate cake, you might use tags like “chocolate,” “cake,” and “dessert.”

2. Custom Taxonomies

Custom taxonomies allow developers to create their own taxonomy types for better content organization.

For instance, if you have a movie review site, you might create a custom taxonomy called “Genre” to categorize your posts into “Action,” “Drama,” “Comedy,” etc.

Custom taxonomies can be either hierarchical (like categories) or non-hierarchical (like tags), depending on how you define them.

Creating Custom Taxonomies

Creating a custom taxonomy in WordPress involves using the register_taxonomy() function.

Add this code to your child theme’s functions.php file or to a must-use plugin.

Here is an example of how to create a custom taxonomy:

function create_movie_genre_taxonomy() {
    register_taxonomy(
        'genre',
        'post',
        array(
            'label'        => __( 'Genres' ),
            'rewrite'      => array( 'slug' => 'genre' ),
            'hierarchical' => true,
            'show_in_rest' => true,
        )
    );
}
add_action( 'init', 'create_movie_genre_taxonomy' );

In this example, a hierarchical taxonomy called “Genre” is created for the “post” post type.

Users can create parent and child genres, similar to how categories work.

The register_taxonomy() function accepts three arguments:

1. $taxonomy – The taxonomy name (lowercase, max 32 characters, letters and underscores only).
2. $object_type – The post type(s) to attach the taxonomy to (e.g., 'post', 'page', or a custom post type slug).
3. $args – An array of arguments that control the taxonomy’s behavior, including label, labels, hierarchical, public, show_ui, show_in_rest, rewrite, and more.

For a full list of arguments, refer to the official register_taxonomy() documentation.

Be careful not to use WordPress reserved terms (such as type, status, or name) as your taxonomy slug. Using a reserved term will cause conflicts and unexpected behavior.

Once your taxonomy is registered, WordPress automatically creates a management screen where you can add, edit, and organize terms.

The screenshot below shows the Genre taxonomy page with three sample terms – Action, Drama, and Comedy:

Real-World Use Cases for Taxonomies

Taxonomies are useful in various real-world scenarios, including:

• Online Stores: An e-commerce website can use custom taxonomies to categorize products by type, brand, and other attributes, making it easier for customers to filter and find items.
• Recipe Blogs: A cooking blog can utilize custom taxonomies to categorize recipes by dietary preferences (e.g., vegan, gluten-free) or by cuisine type (e.g., Italian, Mexican).
• Event Websites: Sites that list events can use taxonomies to categorize events by type (e.g., concerts, workshops) and location, helping users find events that interest them.

Using Taxonomies in Your Theme

Once you have created your custom taxonomy, you can display it in your theme.

Use the get_terms() function to retrieve all terms in a taxonomy:

$genres = get_terms( 'genre' );

foreach ( $genres as $genre ) {
    echo '<li>' . esc_html( $genre->name ) . '</li>';
}

This code retrieves all the terms in the “Genre” taxonomy and displays them in a list.

When editing a post in the block editor, your custom taxonomy appears as a panel in the sidebar.

For hierarchical taxonomies like the Genre example above, WordPress displays checkboxes that let you assign terms to each post:

Taxonomy Queries

You can also query posts by taxonomy using the WP_Query class. For example, to retrieve all posts in a specific genre:

$query = new WP_Query( array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'genre',
            'field'    => 'slug',
            'terms'    => 'action',
        ),
    ),
) );

This code returns all posts that belong to the “Action” genre.

If you change a term’s slug after it has been created, remember to re-save your permalink settings under Settings > Permalinks. Otherwise, the old slug may still be cached and cause 404 errors.

The tax_query argument supports several parameters:

• relation – The logical relationship between multiple taxonomy queries ('AND' or 'OR').
• taxonomy – The taxonomy name.
• field – How to identify terms: 'slug', 'name', 'id', or 'term_taxonomy_id'.
• terms – The term(s) to query for, matching the chosen field.
• include_children – Whether to include child terms in hierarchical taxonomies.
• operator – The comparison operator ('IN', 'NOT IN', 'AND', 'EXISTS', 'NOT EXISTS').

Here is an example that queries posts matching two taxonomies at once – only posts in the “Action” genre and tagged with the “Featured” label:

$query = new WP_Query( array(
    'post_type' => 'post',
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'genre',
            'field'    => 'slug',
            'terms'    => 'action',
        ),
        array(
            'taxonomy' => 'label',
            'field'    => 'slug',
            'terms'    => 'featured',
        ),
    ),
) );

To retrieve posts that match either taxonomy instead of both, change the relation to 'OR'.

You can also pass multiple terms in a single taxonomy query by using an array:

'terms' => array( 'action', 'drama' )

For a deeper look at modifying WordPress queries, check out the post on how to modify the WordPress loop with pre_get_posts.

Benefits of Using Taxonomies

Taxonomies provide several benefits for organizing content in WordPress:

• Improved Organization: Taxonomies help keep your content organized, making it easier for users to find related posts.
• Enhanced Navigation: By categorizing content, you can create better navigation structures, such as filterable archives.
• SEO Benefits: Well-organized content can improve SEO, as search engines can better understand the relationships between different posts.

FAQs

Common questions about WordPress taxonomies:

Summary

WordPress taxonomies are a powerful feature that allows you to categorize and organize your content effectively.

Whether you are using built-in taxonomies like categories and tags or creating your own custom taxonomies, understanding how to leverage them can enhance both user experience and SEO.

For more detailed information on taxonomies, check out the official WordPress Developer Resources.