Categories and tags get you far. Then one day they don’t. You’re running a recipe site and you want to sort by cuisine, or a directory and you need to file listings by region. Bending tags to do that job always feels like a hack. That’s the moment custom taxonomies earn their keep.
This entry in the Mastering Advanced WordPress Development series shows you how to build one. We’ll cover what a taxonomy actually is, when a custom one pays off, and the exact code to register it, including the couple of gotchas that trip people up the first time.
Part 1: What are WordPress custom taxonomies?
A taxonomy is just a system for grouping content. WordPress ships with two: categories and tags. Categories are hierarchical, so they nest into parent and child, which suits broad topic buckets. Tags are flat, a loose pile of keywords with no structure.
A custom taxonomy is one you define yourself. You pick the name, the terms, and whether it behaves like a category or a tag. The point is a grouping that fits your content instead of forcing your content into someone else’s shape.
Part 2: Creating a WordPress custom taxonomy
Step 1: Register the taxonomy
You register a taxonomy with register_taxonomy(), and it has to run on the init hook. Do it any earlier and WordPress isn’t ready; do it any later and the rewrite rules and admin UI won’t wire up. Register it before or alongside any custom post type you plan to attach it to, and name that post type in the second argument.
Drop this in your theme’s functions.php or, better for anything you want to keep, a small site plugin so it survives a theme switch.
<?php
/**
* Registers a custom taxonomy for posts
*/
function custom_taxonomy() {
// Set the labels for the custom taxonomy.
$labels = array(
'name' => esc_html__( 'Name', 'taxonomy general name' ), // The plural name for the taxonomy. Default is 'Categories'/'Tags'.
'singular_name' => esc_html__( 'Singular Name', 'taxonomy singular name' ), // The singular name for the taxonomy. Default is 'Category'/'Tag'.
'search_items' => esc_html__( 'Search Items' ), // The label for the search items field. Default is 'Search Categories'/'Search Tags'.
'popular_items' => esc_html__( 'Popular Items' ), // The label for the popular items field. Default is 'Popular Categories'/'Popular Tags'.
'all_items' => esc_html__( 'All Items' ), // The label for the all items field. Default is 'All Categories'/'All Tags'.
'parent_item' => esc_html__( 'Parent Item' ), // The label for the parent item field. Default is 'Parent Category'/'Parent Tag'.
'parent_item_colon' => esc_html__( 'Parent Item:' ), // The label for the parent item field with colon. Default is 'Parent Category:'/'Parent Tag:'.
'edit_item' => esc_html__( 'Edit Item' ), // The label for the edit item field. Default is 'Edit Category'/'Edit Tag'.
'view_item' => esc_html__( 'View Item' ), // The label for the view item field. Default is 'View Category'/'View Tag'.
'update_item' => esc_html__( 'Update Item' ), // The label for the update item field. Default is 'Update Category'/'Update Tag'.
'add_new_item' => esc_html__( 'Add New Item' ), // The label for the add new item field. Default is 'Add New Category'/'Add New Tag'.
'new_item_name' => esc_html__( 'New Item Name' ), // The label for the new item name field. Default is 'New Category Name'/'New Tag Name'.
'separate_items_with_commas' => esc_html__( 'Separate Items with Commas' ), // The label for the separate items with commas field. Default is 'Separate Categories with commas'/'Separate Tags with commas'.
'add_or_remove_items' => esc_html__( 'Add or Remove Items' ), // The label for the add or remove items field. Default is 'Add or remove categories'/'Add or remove tags'.
'choose_from_most_used' => esc_html__( 'Choose from the Most Used' ), // The label for the choose from the most used field. Default is 'Choose from the most used categories'/'Choose from the most used tags'.
'not_found' => esc_html__( 'Not Found' ), // The label for the not found field. Default is 'No categories found'/'No tags found'.
'no_terms' => esc_html__( 'No Items' ), // The label for the no terms field. Default is 'No categories'/'No tags'.
'menu_name' => esc_html__( 'Menu Name' ), // The label for the menu name field. Default is the same as 'name'.
'name_admin_bar' => esc_html__( 'Name Admin Bar' ), // The label for the name displayed in the admin bar. Default is the same as 'singular_name'.
);
// Set the arguments for the custom taxonomy.
$args = array(
'labels' => $labels, // (array) An array of labels for the taxonomy. Default is an empty array.
'public' => true, // (bool) Whether the taxonomy should be publicly queryable. Default is true.
'show_ui' => true, // (bool) Whether to show the taxonomy user interface. Default is true.
'show_in_nav_menus' => true, // (bool) Whether the taxonomy should be available in navigation menus. Default is true.
'show_tagcloud' => true, // (bool) Whether the taxonomy should be displayed in the tag cloud widget. Default is true.
'meta_box_cb' => null, // (callable) A callback function to render the meta box for this taxonomy. Default is null.
'show_admin_column' => false, // (bool) Whether to show the taxonomy in the admin column. Default is false.
'description' => '', // (string) A short description of the taxonomy. Default is an empty string.
'hierarchical' => false, // (bool) Whether the taxonomy should be hierarchical (like categories) or flat (like tags). Default is false.
'update_count_callback' => '', // (callable) A callback function to update the term count for this taxonomy. Default is an empty string.
'query_var' => true, // (bool|string) Whether to allow querying of this taxonomy via the URL. Default is true.
'rewrite' => true, // (bool|array) Whether to allow URL rewriting for this taxonomy, and what the URL should look like. Default is true.
'sort' => false, // (bool) Whether to sort the terms in this taxonomy. Default is false.
'capabilities' => array(), // (array) An array of capabilities for this taxonomy. Default is an empty array.
'show_in_rest' => false, // (bool) Whether the taxonomy should be available in the REST API. Default is false.
'rest_base' => null, // (string) The base URL for the REST API route. Default is null, which means the taxonomy name is used.
'rest_controller_class' => 'WP_REST_Terms_Controller', // (string) The class to use for the REST API controller. Default is 'WP_REST_Terms_Controller'.
);
// Register the custom taxonomy.
register_taxonomy( 'custom_taxonomy', array( 'post' ), $args );
}
// Add the custom taxonomy to the WordPress init hook
add_action( 'init', 'custom_taxonomy' );Make it yours by changing two things. Swap 'custom_taxonomy' in the register_taxonomy() call for your own slug, and edit the label strings so the admin screens read the way you want. The second argument, array( 'post' ), is the list of post types the taxonomy attaches to, so add your own post type there if you’re not using plain posts.
Two arguments in that $args array are worth a second look:
hierarchical decides the whole feel of the thing. Set it to true and you get category-style nesting with parent and child terms and checkboxes in the editor. Leave it false and it behaves like tags, a comma-separated free-for-all. Pick based on your content, not habit.
show_in_rest is set to false in the example above, and that has a real consequence: your taxonomy won’t show up in the block editor. If you’re on Gutenberg and want the meta box in the sidebar, set show_in_rest to true. Miss this and you’ll swear the code is broken when it’s just hidden.
One more thing the snippet leaves out. Custom rewrite rules for your taxonomy’s archive URLs don’t take effect until the rewrite rules are flushed. During development a visit to Settings > Permalinks does it by hand. For a plugin, call flush_rewrite_rules() on activation, after your taxonomy is registered, and never on init on every page load, which is a known performance mistake.
Step 2: Use your custom taxonomy
Once it’s registered, the taxonomy shows up when you edit a post of the type you attached it to. For a hierarchical taxonomy you’ll see a checkbox box like Categories; for a flat one, a text field like Tags. Add your terms there, save, and your content is grouped.
Wrapping up
That’s the whole job: register the taxonomy on init, decide hierarchical or flat, and mind the two quiet defaults, show_in_rest for the block editor and flushing rewrite rules for clean URLs. Get those right and you’ve got a categorization system that actually matches the site you’re building instead of the one WordPress guessed you wanted.