Custom taxonomies

A taxonomy is a way of grouping content. WordPress has two built in: Categories and Tags. A custom taxonomy adds your own, such as Genres for Books or Cities for Events. Each entry in a taxonomy is a term (for example "Fantasy").

Taxonomies are available on every plan. They work on any post type, including custom post types.

Two shapes exist:

Where to find it

Open WPM Fields › Taxonomies. Its list has these columns: Key, Plural label, Post types, Status and REST API. Click a row to edit it or Add taxonomy to create one.

Create a taxonomy

1. Click Add taxonomy.
2. Fill in Plural label ("Genres") and Singular label ("Genre").
3. Check the Taxonomy key (filled in from the singular label until you edit it).
4. Under Post types tick every type the taxonomy belongs to. The default is Post.
5. Choose Hierarchical for category-style or leave it off for tag-style.
6. Click Create taxonomy. You see "Taxonomy created."

The new taxonomy appears under each chosen post type's menu (or the Posts menu) as an extra screen.

The Basics section

Key rules

You will see these messages when something is wrong:

• "Taxonomy key is required."
• "Taxonomy key must be 1–20 characters: lowercase letters, numbers, hyphens, underscores only."
• "A taxonomy with this key already exists in Mass Custom Fields."
• "This taxonomy key is reserved by WordPress." Core taxonomies (category, post_tag, post_format, nav_menu, link_category and others) and reserved query words (type, name, year, term, tag, search and so on) are refused.
• "This taxonomy is already registered by WordPress or another plugin."
• Post type "key" does not exist. A post type you ticked is inactive or not registered.

Advanced tabs

General

The default term is created the first time the taxonomy is registered after you save it.

Labels

The same behaviour as for post types: 24 label fields show the generated default as a grey placeholder, an empty field uses the default, Regenerate from labels fills all with defaults (and stores them as overrides), Clear overrides empties them. See General and Labels.

Keys: name, singular_name, menu_name, all_items, edit_item, view_item, update_item, add_new_item, new_item_name, parent_item, parent_item_colon, search_items, popular_items, separate_items_with_commas, add_or_remove_items, choose_from_most_used, not_found, no_terms, items_list_navigation, items_list, most_used, back_to_items, item_link, item_link_description.

Visibility

Meta box options:

A custom callback must be a WordPress meta box function (post_categories_meta_box, post_tags_meta_box) or be allowed with the filter wpmcf/taxonomies/allowed_callbacks. Otherwise saving fails with "Meta box callback must be a WordPress meta box function or one allowed by the wpmcf/taxonomies/allowed_callbacks filter." Meta box sanitization callback (optional) follows the same rule.

add_filter( 'wpmcf/taxonomies/allowed_callbacks', function ( array $allowed, string $arg ) {
	if ( 'meta_box_cb' === $arg ) {
		$allowed[] = 'my_genre_meta_box';
	}
	return $allowed;
}, 10, 2 );

URLs

Changing URLs sets a rewrite flush that runs on the next page load. You do not need to resave Settings › Permalinks. See Custom post types.

REST API

Same four fields as for post types: Show in the REST API (On), REST base, REST namespace (wp/v2) and REST controller class (optional). Show in the REST API must be on for the block editor to show the taxonomy panel. See Permissions and REST API.

Permissions

Capability names are cleaned to lowercase letters, numbers, hyphens and underscores. Leave a field empty to keep WordPress's default for that action.

Attach a taxonomy to a post type

There are two equivalent ways:

• In the taxonomy: tick the post types under Post types.
• In the post type: tick the taxonomy under Taxonomies on the General tab (General and Labels). This is also how you add the built-in Categories or Tags to a custom type.

Taxonomies are registered before post types on every request, so the order of creation does not matter once both are saved. However, the two must exist when you save: you cannot attach a taxonomy to a post type that is inactive or does not exist yet.

Edit, deactivate and delete

• Edit: everything except the key. Click Save changes; you see "Taxonomy saved."
• Active off: the taxonomy is no longer registered. Terms and their assignments remain in the database but cannot be used.
• Delete (trash icon): "This removes the registration for «key». Terms and assignments may remain in the database." Existing terms are not deleted. Recreate a taxonomy with the same key to bring them back.

Use terms on your site

Taxonomies are registered with WordPress, so the usual functions work:

$terms = get_terms( array( 'taxonomy' => 'genre', 'hide_empty' => false ) );

$books = new WP_Query( array(
	'post_type' => 'book',
	'tax_query' => array(
		array( 'taxonomy' => 'genre', 'field' => 'slug', 'terms' => 'fantasy' ),
	),
) );

To store extra data on terms, create a field group with the Taxonomy location rule, see Field groups.

Hooks

wpmcf/taxonomies/before_register, wpmcf/taxonomies/register_args, wpmcf/taxonomies/after_register and wpmcf/taxonomies/allowed_callbacks work like their post type counterparts. See Hooks.

Troubleshooting

The taxonomy is not in the editor. Check Active, Show in admin, that the post type is ticked, and that Meta box is not "None". For the block editor, Show in the REST API must be on.

"Post type … does not exist." The post type is inactive, deleted, or created in the same moment. Save the post type first, reload, then attach it.

Term pages return 404. The permalink structure is Plain, the slug clashes with a page, or Publicly queryable is off. Wait for the next page load after a change.

The default term does not appear. Reload the admin once after saving; it is created on the next registration.