Developing Custom WordPress Taxonomies
A taxonomy in WordPress is a classification system for posts. Built-in ones are "Categories" (hierarchical) and "Tags" (flat). Custom taxonomies are created for any other grouping: project technologies, job specialties, real estate types, film genres. A properly configured taxonomy provides URL-friendly links for each category, filtering in /wp-admin, and parameters for WP_Query. Registration takes a few hours; full setup with taxonomy meta-fields and custom archive pages takes 1 day.
Registration via register_taxonomy
add_action('init', function () {
// Hierarchical taxonomy (like categories)
register_taxonomy('project_category', ['project'], [
'labels' => [
'name' => 'Project Categories',
'singular_name' => 'Category',
'search_items' => 'Search Categories',
'all_items' => 'All Categories',
'parent_item' => 'Parent Category',
'parent_item_colon' => 'Parent Category:',
'edit_item' => 'Edit',
'update_item' => 'Update',
'add_new_item' => 'Add Category',
'new_item_name' => 'New Category',
'menu_name' => 'Categories',
],
'hierarchical' => true,
'show_ui' => true,
'show_admin_column' => true,
'query_var' => true,
'rewrite' => ['slug' => 'project-category', 'hierarchical' => true],
'show_in_rest' => true,
'rest_base' => 'project-categories',
]);
// Flat taxonomy (like tags) — tech stack
register_taxonomy('tech_stack', ['project', 'case'], [
'labels' => [
'name' => 'Technologies',
'singular_name' => 'Technology',
'add_new_item' => 'Add Technology',
'search_items' => 'Search Technologies',
'all_items' => 'All Technologies',
],
'hierarchical' => false,
'show_ui' => true,
'show_admin_column' => true,
'query_var' => true,
'rewrite' => ['slug' => 'tech'],
'show_in_rest' => true,
]);
});
show_in_rest => true is necessary for the taxonomy to work in the Gutenberg editor. show_admin_column => true adds a column with terms to the post list.
Using in WP_Query
// Projects in "web" category with "react" tag
$projects = new WP_Query([
'post_type' => 'project',
'posts_per_page' => 12,
'tax_query' => [
'relation' => 'AND',
[
'taxonomy' => 'project_category',
'field' => 'slug',
'terms' => 'web',
],
[
'taxonomy' => 'tech_stack',
'field' => 'slug',
'terms' => ['react', 'next-js'],
'operator' => 'IN',
],
],
'orderby' => 'date',
'order' => 'DESC',
]);
Meta-Fields for Taxonomy Terms
Starting with WordPress 4.4, taxonomy terms have meta-fields via add_term_meta/get_term_meta. Example: add an icon and color to a project category:
// Fields on term addition page
add_action('project_category_add_form_fields', function (string $taxonomy): void {
?>
<div class="form-field">
<label for="term-color">Category Color</label>
<input type="color" id="term-color" name="term_color" value="#1a1a2e">
<p>Color for display in lists and project cards</p>
</div>
<div class="form-field">
<label for="term-icon">Icon (SVG code or dashicons class)</label>
<input type="text" id="term-icon" name="term_icon" value="">
</div>
<?php
});
// Fields on term edit page
add_action('project_category_edit_form_fields', function (WP_Term $term): void {
$color = get_term_meta($term->term_id, 'color', true) ?: '#1a1a2e';
$icon = get_term_meta($term->term_id, 'icon', true);
?>
<tr class="form-field">
<th><label for="term-color">Color</label></th>
<td><input type="color" id="term-color" name="term_color" value="<?= esc_attr($color) ?>"></td>
</tr>
<tr class="form-field">
<th><label for="term-icon">Icon</label></th>
<td><input type="text" id="term-icon" name="term_icon" value="<?= esc_attr($icon) ?>"></td>
</tr>
<?php
});
// Save
add_action('created_project_category', 'save_project_category_meta');
add_action('edited_project_category', 'save_project_category_meta');
function save_project_category_meta(int $term_id): void {
if (isset($_POST['term_color'])) {
update_term_meta($term_id, 'color', sanitize_hex_color($_POST['term_color']));
}
if (isset($_POST['term_icon'])) {
update_term_meta($term_id, 'icon', sanitize_text_field($_POST['term_icon']));
}
}
Frontend usage:
$terms = get_the_terms(get_the_ID(), 'project_category');
foreach ($terms as $term) {
$color = get_term_meta($term->term_id, 'color', true) ?: '#ccc';
$icon = get_term_meta($term->term_id, 'icon', true);
printf(
'<a href="%s" class="tag" style="--tag-color:%s">%s%s</a>',
esc_url(get_term_link($term)),
esc_attr($color),
$icon ? '<span class="tag__icon">' . esc_html($icon) . '</span>' : '',
esc_html($term->name)
);
}
Custom Term Order
By default, terms are displayed alphabetically. For manual order, use term_order via plugin or meta-field:
add_action('edited_project_category', function (int $term_id): void {
if (isset($_POST['term_order'])) {
update_term_meta($term_id, 'order', absint($_POST['term_order']));
}
});
// Sort on output
$terms = get_terms([
'taxonomy' => 'project_category',
'hide_empty' => false,
'meta_key' => 'order',
'orderby' => 'meta_value_num',
'order' => 'ASC',
]);
Taxonomy on Multiple CPTs
One taxonomy can serve multiple post types—"tech stack" for both projects and cases. After registration, add a type to an existing taxonomy:
register_taxonomy_for_object_type('tech_stack', 'case');
Taxonomy Archive Template
WordPress finds the archive template by hierarchy: taxonomy-{tax}-{term}.php → taxonomy-{tax}.php → taxonomy.php → archive.php. In FSE themes—similarly via templates/taxonomy-project_category.html.
Performance
Queries on taxonomies with large numbers of terms and posts can be slow. Several rules:
- Always use
'fields' => 'ids'inget_terms()if you need only IDs - With
tax_querywith multiple taxonomies—check query plan viaEXPLAIN - For public filters with large archives—use Elasticsearch or cache results via Redis