How to Register Custom Taxonomy in WordPress Easily

To register a custom taxonomy in WordPress, use the register_taxonomy function inside a hook like init. This function links your taxonomy to one or more post types and defines labels and behavior.

Syntax

The register_taxonomy function requires three main parts: the taxonomy name, the post type(s) it applies to, and an array of arguments to customize labels and behavior.

• taxonomy: A unique string ID for your taxonomy (e.g., 'genre').
• object_type: The post type or array of post types to attach the taxonomy to (e.g., 'post').
• args: An array of options like labels, hierarchical (true for categories, false for tags), and rewrite rules.

php

register_taxonomy( string $taxonomy, string|array $object_type, array $args = array() )

Example

This example registers a hierarchical custom taxonomy called Genre for posts. It shows how to add labels and make it behave like categories.

php

<?php
function register_genre_taxonomy() {
    $labels = array(
        'name' => 'Genres',
        'singular_name' => 'Genre',
        'search_items' => 'Search Genres',
        'all_items' => 'All Genres',
        'parent_item' => 'Parent Genre',
        'parent_item_colon' => 'Parent Genre:',
        'edit_item' => 'Edit Genre',
        'update_item' => 'Update Genre',
        'add_new_item' => 'Add New Genre',
        'new_item_name' => 'New Genre Name',
        'menu_name' => 'Genres',
    );

    $args = array(
        'hierarchical' => true,
        'labels' => $labels,
        'show_ui' => true,
        'show_admin_column' => true,
        'query_var' => true,
        'rewrite' => array('slug' => 'genre'),
    );

    register_taxonomy('genre', array('post'), $args);
}
add_action('init', 'register_genre_taxonomy');

Output

A new taxonomy 'Genre' appears in the WordPress admin menu under Posts, allowing hierarchical categorization of posts.

Common Pitfalls

Common mistakes when registering custom taxonomies include:

• Not hooking register_taxonomy to init, causing the taxonomy not to register properly.
• Using a taxonomy name that conflicts with existing taxonomies or reserved terms.
• Forgetting to set hierarchical correctly: true for category-like, false for tag-like taxonomies.
• Not providing labels, which leads to poor admin UI display.

php

<?php
// Wrong: calling register_taxonomy outside init hook
register_taxonomy('genre', 'post', array('hierarchical' => true));

// Right: inside init hook
add_action('init', function() {
    register_taxonomy('genre', 'post', array('hierarchical' => true));
});

Quick Reference

Parameter	Description	Example
taxonomy	Unique ID for taxonomy	'genre'
object_type	Post type(s) to attach taxonomy	'post' or ['post', 'page']
hierarchical	True for categories, false for tags	true
labels	Array of UI labels	['name' => 'Genres', 'menu_name' => 'Genres']
rewrite	URL slug settings	['slug' => 'genre']
show_ui	Show in admin UI	true
show_admin_column	Show taxonomy column in post list	true

Key Takeaways

Always register custom taxonomies inside the 'init' action hook.

Use a unique taxonomy name to avoid conflicts with core or plugins.

Set 'hierarchical' to true for category-like taxonomies and false for tag-like.

Provide clear labels for better admin interface usability.

Attach your taxonomy to the correct post types using the object_type parameter.