WordPress Custom Taxonomy Registration

register_taxonomy() is WordPress’s API for creating content grouping systems beyond the built-in Categories and Tags. It takes three arguments: the taxonomy slug (a lowercase string, max 32 characters, no spaces — 'project_type'), the post type it attaches to ('project' or an array of post types), and a configuration args array. WordPress stores the taxonomy in the global $wp_taxonomies object on every request and generates admin UI panels, URL rewrite rules, and database query capabilities from these args. The function must be called on or after the init hook — WordPress’s rewrite system and post type registry aren’t initialized until then. The minimum viable args are public => true (makes terms visible in admin and front-end archives) and labels with at least name and singular_name. Every other arg falls back to a WordPress default.

The labels array maps to specific UI contexts. menu_name controls the admin sidebar item. all_items and search_items appear in the list table header. edit_item, add_new_item, and new_item_name appear on the term edit screen. not_found shows in the metabox when no terms match a search. Hierarchical taxonomies add two labels flat ones omit: parent_item appears in the parent dropdown on the term edit screen, and parent_item_colon is the same label with a colon appended, used in the quick-edit form. If you omit any label, WordPress falls back to a generic phrase from the built-in category or tag labels — which is why the editor might read “Add New Category” instead of “Add New Project Type” if add_new_item is missing. Wrapping every string in __() with your text domain makes every label translatable the moment a translator adds a .po file.

Rewrite rules translate your taxonomy into navigable URLs. Without rewrite, WordPress uses the raw taxonomy slug as the URL segment — /project_type/ — including underscores and matching the internal identifier exactly. The slug inside the rewrite array sets a human-friendly prefix: array( 'slug' => 'project-type' ) produces clean URLs like /project-type/web-design/. Like post type rewrites, taxonomy rewrites are stored in the rewrite_rules option in the database and require a flush when changed — visit Settings → Permalinks and click Save. show_in_rest => true registers REST endpoints at /wp-json/wp/v2/project_type and enables the Gutenberg sidebar panel. Without it, the block editor shows no taxonomy UI at all. show_admin_column => true adds a taxonomy column to the CPT list table — clicking a term in that column filters the list to posts assigned that term, which speeds up editorial workflows considerably.

The hierarchical boolean changes four things at once. In the admin editor: true renders a scrollable checkbox list with a parent selector beneath it (identical to the Categories metabox); false renders a comma-delimited tag input that auto-suggests existing terms (identical to the Tags metabox). In the database: hierarchical terms store a parent column in wp_terms — flat terms always have parent = 0. In templates: get_the_terms() returns a flat array for both types, but hierarchical results can be passed to get_term_children() to walk the parent-child tree. In URL structure: hierarchical taxonomies support nested term slugs like /project-type/digital/web-design/; flat taxonomies produce single-level slugs only. Choose hierarchical when terms have natural groupings (Web → Front-end → Vue.js). Choose flat when terms are independent labels without a hierarchy (healthcare, retail, fintech).

Three apply_filters() calls expose the taxonomy’s configurable parts as extension points. A child theme overrides any of them with a single add_filter() call — no file editing, no update conflicts. The theme_project_type_labels filter wraps the entire labels array, so a multilingual setup can swap all labels at once. The theme_project_type_slug filter controls the URL rewrite — useful when a white-label client wants /work-category/ instead of /project-type/. The theme_project_type_objects filter controls which post types the taxonomy attaches to — a child theme that adds a case_study post type can register it under the same taxonomy without touching the parent theme: add_filter( 'theme_project_type_objects', function( $types ) { $types[] = 'case_study'; return $types; } ). The parent theme ships with sensible defaults; every client customization lives in the child theme’s filters.

Place the file and require it. Copy the Step 5 code into inc/taxonomy-project-type.php. In functions.php, add this line near the top — after the theme setup function but before any template-specific includes:

require_once get_template_directory() . '/inc/taxonomy-project-type.php';

For multiple taxonomies, create one file per taxonomy (taxonomy-project-tag.php, taxonomy-service-type.php) and require each. This keeps each taxonomy’s registration isolated — easier to debug and easy to remove without affecting the others.

Flush the rewrite rules. After adding the require line, visit Settings → Permalinks in the WordPress admin and click “Save Changes” — you don’t need to change any setting, just save. This calls flush_rewrite_rules() internally, rebuilding the URL routing table to include your new taxonomy slug. Without this step, term archive URLs like /project-type/web-design/ return a 404. On a staging-to-production deploy, trigger this manually from the Permalinks page after deploy, or add a one-time flush_rewrite_rules() call to your deploy script.

Test in the admin. Go to Project Types in the wp-admin sidebar (it appears below the Projects menu item). Click “Add New Project Type”, enter a name (e.g. “Web Design”), and save. Open any published Project post and assign the term from the Project Types metabox on the right. Update the post, then visit the term archive at yoursite.com/project-type/web-design/ — you should see the post listed. If you get a 404, go back to step 2 and flush permalinks. For fast debugging, add var_dump( get_terms( array( 'taxonomy' => 'project_type' ) ) ); to a template to confirm the taxonomy is registered and the term was created.

Display assigned terms in a template. Use get_the_terms() inside any post loop. It returns an array of term objects — each has name, slug, term_id, and description properties. get_term_link() returns the full URL to the term’s archive page. Always check for is_wp_error() — if the taxonomy slug is wrong or the taxonomy isn’t registered, get_the_terms() returns a WP_Error object, which crashes a foreach.

<?php
$terms = get_the_terms( get_the_ID(), 'project_type' );
if ( $terms && ! is_wp_error( $terms ) ) {
    ?>
    <ul class="project-types">
    <?php
    foreach ( $terms as $term ) {
        $url = get_term_link( $term );
        ?>
        <li>
            <a href="<?php echo esc_url( $url ); ?>">
                <?php echo esc_html( $term->name ); ?>
            </a>
        </li>
        <?php
    }
    ?>
    </ul>
    <?php
}

Create a taxonomy archive template. WordPress checks for template files in this order: taxonomy-{taxonomy}-{term}.php → taxonomy-{taxonomy}.php → taxonomy.php → archive.php → index.php. Create taxonomy-project_type.php in your theme root and it loads automatically for every Project Type term archive — no routing code needed. Use get_queried_object() inside the template to get the current term and display its name or description in the archive header.

<?php
get_header();
$term = get_queried_object();
?>
<main class="taxonomy-archive">
    <h1><?php echo esc_html( $term->name ); ?></h1>
    <?php if ( $term->description ) { ?>
        <p class="taxonomy-desc"><?php echo esc_html( $term->description ); ?></p>
    <?php } ?>
    <?php if ( have_posts() ) { ?>
        <ul class="post-list">
        <?php
        while ( have_posts() ) {
            the_post();
            ?>
            <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
            <?php
        }
        ?>
        </ul>
    <?php } ?>
</main>
<?php
get_footer();

Attach the taxonomy to multiple post types. Pass an array as the second argument to register_taxonomy(). Terms you create for project_type are shared across all attached post types — the same term entry in the database. The taxonomy metabox appears in the editor for all listed post types. You can also attach a taxonomy after registration using register_taxonomy_for_object_type( 'project_type', 'post' ) — useful when you want the registration in one file and the attachment in another (e.g. a plugin that adds a taxonomy to a theme’s CPT).

<?php
add_action( 'init', function() {
    register_taxonomy( 'project_type', array( 'project', 'post' ), array(
        'labels' => array(
            'name'          => __( 'Project Types', 'textdomain' ),
            'singular_name' => __( 'Project Type', 'textdomain' ),
        ),
        'public'            => true,
        'hierarchical'      => true,
        'rewrite'           => array( 'slug' => 'project-type' ),
        'show_in_rest'      => true,
        'show_admin_column' => true,
    ) );
} );