register_taxonomy – WordPress Function to Create or Modify Taxonomy

Updated:

/

In WordPress, a taxonomy is a grouping method for any post type.

WordPress has five built-in taxonomies: category, post_tag, nav_menu, post_format and link_category. category, post_tag and post_format are used for the post_type post, nav_menu is used for the post_type nav_menu_item, and link_category is used for the post_type link. When the built-in taxonomies are not enough, custom taxonomies are created to group things in more ways.

Source Reference:

The register_taxonomy function is located in the wp-includes/taxonomy.php file. In the same file, inside the create_initial_taxonomies() function, you can check how WordPress uses register_taxonomy for creating the initial taxonomies like category, post_tag etc.

Using register_taxonomy:

To create or modify a custom taxonomy, use the function register_taxonomy. This function accepts three arguments.

1. taxonomy name is a unique lowercase string, which is used later on to query terms under the taxonomy or assign a term to a post type. No numbers, no spaces & no uppercase letters.

2. post object type is the post type name the taxonomy will be used with. The post type can be already registered or registered later.

3. third argument is an array of information that sets the display name, usage restrictions and some other things.

Important options for the Third argument of register_taxonomy function:

hierarchical

A taxonomy has terms, generally visible with a post or custom post type. Ex: when we create a category English, the English is called a term of the category taxonomy. We may need to create sub terms, ex: new sub-terms US English and UK English under the term English. This is where we need the hierarchical argument. If we need a parent => sub terms relation, hierarchical needs to be set true, else set it false.

query_var

If you have used the WordPress WP_Query or get_posts function, you should have seen how you can query posts by a category name or id. Example: get_posts( array( ‘category_name’ => ‘uncategorized’) ). Here category_name is the query variable. So the query variable is heavily used in queries. Setting query_var to false will restrict querying posts by using the query_var.

If you register a custom taxonomy, ex: the taxonomy name is books and a term exists in this taxonomy called tutorial, and you set the query_var argument to true, you can query for the posts belonging to the custom taxonomy (ex: “books” => “tutorial”). If the 'query_var' argument is set to false, you can’t make this query as it won’t get you any result.

You should only set 'query_var' to 'false' if you want to use the custom taxonomy with raw PHP MYSQL queries, else set it to true for easy usage.

rewrite

Rewrite is the url formation you want to use for taxonomy terms. Example: A general category page url looks like – ‘http://SITEURL/category/the_category_term/’. Here ‘category’ is the taxonomy, and the_category_term is a term slug. Each taxonomy displays its terms in the format – http://SITEURL/taxonomy/term_slug/. To show a custom taxonomy’s terms with a different front rather than the taxonomy name, the rewrite argument is used. Setting this argument to false will use the query variable in the url like this: http://SITEURL/?taxonomy_name=the_term_name. rewrite accepts parameters as an array. Ex: ‘rewrite’ => array(‘slug’ => ‘the_slug_you_need_to_show_before_the_term_name’)

show_in_rest

Setting 'show_in_rest' to true exposes the taxonomy in the REST API, and it is also required for the taxonomy panel to appear in the block editor. If your custom taxonomy doesn’t show up while editing a post in the block editor, this argument is the reason.

Example

Create a new taxonomy tutorial for the default post_type post.

add_action( 'init', 'register_custom_taxonomies', 0 );
function register_custom_taxonomies() {
    register_taxonomy( 'tutorial', 'post', array(
	'hierarchical' => true,
	'labels' => array(
	    'name'          => 'Tutorials',
	    'singular_name' => 'Tutorial'
	),
	'query_var' => true,
	'rewrite' => array(
            'slug' => 'tutorial',
	    'with_front' => false
	),
	'public' => true,
	'show_ui' => true,
	'show_in_rest' => true,
	'show_tagcloud' => true,
	'show_in_nav_menus' => false
    ));
}

See here, we have called the register_taxonomy function inside a new function register_custom_taxonomies, as register_taxonomy needs to be called after the init action is fired. So we create a function and hook it on the init action event.

You can find the full function reference at the WordPress Documentation