Use WordPress’s register_taxonomy() function to create a custom taxonomy, attach it to the post type that owns the classification, and register it on the init hook. Decide first whether terms need parent-child relationships or independent labels, then configure the taxonomy key, labels, editor visibility, REST support, and rewrite rules. Finally, create and assign terms, query them, and render them in your templates.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What a custom taxonomy does
A taxonomy is WordPress’s system for classifying content with terms. The WordPress Developer Resources Plugin Handbook calls it “a fancy word for the classification/grouping of things.” A taxonomy is separate from the content itself: the taxonomy defines the classification system, while terms are the individual values within it.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
For a video-game site, a custom taxonomy could organize games by genre, platform, developer, setting, or multiplayer mode. The important question is whether the classification is an independent property that deserves its own reusable terms. If a value needs to be selected on many posts, listed in navigation, queried across content, or given an archive page, a taxonomy is usually a better model than typing the value into an ordinary text field.
Registration creates the taxonomy definition, but it does not finish the feature. You still need to create terms, assign them to content, query those assignments, and output the terms or their archive links in the front end.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Choose the data model before writing code
Ask what the labels represent
Start by listing the classifications your editors will actually maintain. A taxonomy works best when its terms have stable meaning and can be reused. For example, a game can belong to several genres, and the same genre can be assigned to many games. That many-to-many relationship is what taxonomies are designed to represent.
Decide which post type owns the taxonomy. The second argument to register_taxonomy() is an object-type string or array. If your custom post type key is game, registering the taxonomy against game makes the terms available to game entries rather than to every post on the site. You can associate one taxonomy with more than one object type when the same classification genuinely applies to each type.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Hierarchical or flat?
Set hierarchical according to the relationships your content needs, not according to whether the labels sound like categories or tags. A hierarchical taxonomy supports parent and child terms and presents a category-style editing experience. A flat taxonomy treats each term as an independent label and presents a tag-style assignment experience.
| Decision area | Hierarchical taxonomy | Flat taxonomy |
|---|---|---|
| Term relationships | Parent and child terms can express groups and subgroups. | Terms are independent and have no parent-child structure. |
| Editing experience | Category-style selection is useful when editors browse a controlled tree. | Tag-style assignment is useful when editors apply several peer labels. |
| Example | A genre taxonomy with a parent such as Action and child terms such as Stealth or Platformer. |
A topic taxonomy in which each topic is an independent label. |
| URL planning | Hierarchical rewrite paths can reflect the parent-child structure when that is appropriate for the site. | Flat rewrite paths keep each term at one level. |
Do not create parent-child levels merely because they look tidy in the dashboard. A hierarchy should describe a real relationship that editors and visitors understand. If terms are simply alternate descriptors, a flat taxonomy avoids unnecessary maintenance.
Plan the taxonomy contract
Before registering anything, write down the values that will become part of your site’s technical interface:
- Taxonomy key: the machine-readable identifier used by PHP, queries, REST responses, and rewrite rules.
- Object type: the post type or types that can receive the terms.
- Term structure: hierarchical or flat.
- Editor labels: the names and instructions shown in the administration screens.
- Visibility: whether the taxonomy is public and whether it needs an administration screen and column.
- REST exposure: whether the block editor and REST API should be able to discover and manage it.
- URL shape: the rewrite slug and whether hierarchical paths are desirable.
- Permissions: capabilities if term management needs rules different from the defaults.
The taxonomy key may be no longer than 32 characters. The current function reference restricts it to lowercase letters, numbers, dashes, and underscores. Treat the key as a permanent API name: avoid collisions with existing taxonomies, post types, and reserved public or private query variables. Changing it later can affect code, REST routes, queries, and indexed URLs.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Register the taxonomy on init
WordPress Developer Resources gives an explicit warning for this function: “Do not use before the ‘init’ hook.” Registering on init ensures WordPress has loaded the post types and is ready to build the taxonomy object.
- Identify the post type key that should receive the terms. In the example below, the custom post type is
game. - Choose a short, unique taxonomy key. The example uses
game_genre. - Define labels and the arguments that control hierarchy, administration, REST access, queries, and URLs.
- Call
register_taxonomy()from a callback attached toinit.
<?php
function vgs_register_game_genre_taxonomy() {
$labels = array(
'name' => 'Genres',
'singular_name' => 'Genre',
'search_items' => 'Search genres',
'all_items' => 'All genres',
'parent_item' => 'Parent genre',
'parent_item_colon' => 'Parent genre:',
'edit_item' => 'Edit genre',
'update_item' => 'Update genre',
'add_new_item' => 'Add new genre',
'new_item_name' => 'New genre name',
'menu_name' => 'Genres',
);
$args = array(
'labels' => $labels,
'description' => 'Genres used to classify games.',
'public' => true,
'show_ui' => true,
'hierarchical' => true,
'show_admin_column' => true,
'query_var' => 'game_genre',
'rewrite' => array(
'slug' => 'game-genre',
'hierarchical' => true,
),
'show_in_rest' => true,
);
register_taxonomy( 'game_genre', array( 'game' ), $args );
}
add_action( 'init', 'vgs_register_game_genre_taxonomy' );Replace game with the exact key used by your custom post type. The post type must exist in the same WordPress installation; a spelling mismatch is enough to make the taxonomy appear unattached.
Understand the registration arguments
register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() ) creates or modifies a taxonomy. The most useful arguments in a first implementation are:
| Argument | What it controls |
|---|---|
labels |
The names displayed in term-management screens, buttons, menus, and editor controls. |
description |
A human-readable explanation of what the taxonomy classifies. |
public |
The taxonomy’s public visibility and the default behavior inherited by several related options. |
show_ui |
Whether WordPress provides an administration interface for managing terms. If omitted, related behavior can inherit from public. |
hierarchical |
Whether terms can have parents and children. |
show_admin_column |
Whether a term column appears in the associated post-type list table. |
query_var |
The query variable used when building taxonomy queries through WordPress’s public query system. |
rewrite |
The public URL settings, including the rewrite slug and whether hierarchical paths are used. |
capabilities |
Permissions for managing and assigning terms when the default capabilities are not suitable. |
show_in_rest |
Whether the taxonomy is exposed to the REST API and available to the block editor. |
Defaults matter. The function reference notes that show_ui and several related options inherit from public unless you specify them. Set the values explicitly when the intended behavior is important, especially on a production site with a customized editorial workflow.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsMake the taxonomy usable in the dashboard
Administration screens and columns
Set show_ui to true when editors need to create, rename, delete, or organize terms in the dashboard. Use clear labels so the interface says Genres rather than exposing an internal key such as game_genre.
show_admin_column is independent of the term-management screen. When it is true, the associated post-type list table can show each item’s assigned terms, making it easier to audit content. It does not replace the editor control; it adds a column to the listing screen.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Assign terms to content
After the code is active, open the administration screen for the associated post type and edit an item. The taxonomy control should appear alongside the other editor fields. Create a few representative terms first, then assign them to several items so you can test both single-term and multiple-term cases. For a hierarchical taxonomy, create at least one parent and child pair and verify that the tree behaves as intended.
Registration alone does not create terms. Terms are records inside the taxonomy and must be added through the dashboard, an import process, code, or the REST API. Likewise, a term does not affect the front end until content is assigned to it and your templates or queries use that assignment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Enable block-editor and REST support separately
Admin visibility and REST availability are distinct choices. A taxonomy can have an administration UI without being available to the block editor or REST clients. Set show_in_rest to true when editors should assign terms in the block editor or when an external client needs to read and manage them through WordPress’s REST API.
You can optionally set rest_base to choose the route base used by the REST controller. The default taxonomy controller is WP_REST_Terms_Controller. Once REST exposure is enabled, the REST API handbook documents two useful discovery endpoints:
/wp/v2/taxonomieslists the taxonomies available through the API./wp/v2/taxonomies/<taxonomy>returns details for one taxonomy.
The discovery schema includes the taxonomy slug, whether it is hierarchical, the associated object types, and REST route information. Use that response to confirm that WordPress registered the key you intended and attached it to the expected post type. If the taxonomy does not appear, check the registration callback, the show_in_rest value, and the taxonomy key.
Design public URLs and rewrite behavior
The rewrite argument controls the public URL structure generated for taxonomy archives. In the example, the slug game-genre keeps taxonomy URLs distinct from the post type’s own URLs. A hierarchical taxonomy can use hierarchical rewrite paths so a child term’s URL reflects its parent; use that only when the hierarchy is meaningful to visitors and stable enough to become part of your information architecture.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Rewrite changes require a one-time flush of WordPress’s rewrite rules. The function reference specifically cautions against flushing on every request or on every plugin or theme load. Flush once after the taxonomy is created or its rewrite settings change, such as during a controlled activation step or by saving the Permalinks settings once in the dashboard. Do not put flush_rewrite_rules() directly in the registration callback that runs on every request.
If a taxonomy archive returns a 404 immediately after registration, the registration code may be correct and the rewrite rules may simply be stale. Flush once, then test again. Repeated flushing adds unnecessary work and can mask configuration problems rather than solving them.
Create a taxonomy archive in your theme
Public taxonomy pages are rendered through the theme’s template hierarchy. A theme can provide a taxonomy-and-term-specific template such as taxonomy-game_genre-rpg.php, a taxonomy-specific template such as taxonomy-game_genre.php, a general taxonomy.php, and then broader archive fallbacks. Choose the narrowest template that matches the presentation you need, while keeping shared markup in reusable template parts.
Inside an archive template, use the main WordPress loop to display the posts assigned to the current term. The archive query is prepared by WordPress from the requested taxonomy URL; your template’s job is to present the results and make the classification clear with a heading, description, and navigation where appropriate.
Do not assume that registering a taxonomy automatically creates a finished archive design. The taxonomy supplies the data and URL; your theme still determines headings, cards, pagination, metadata, and links.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Query content by a custom taxonomy
Use a taxonomy query for selected terms
When you need a custom list rather than the default archive, pass a tax_query to WP_Query. The taxonomy name in the query must exactly match the key passed to register_taxonomy().
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
<?php
$games = new WP_Query( array(
'post_type' => 'game',
'posts_per_page' => 12,
'tax_query' => array(
array(
'taxonomy' => 'game_genre',
'field' => 'slug',
'terms' => array( 'role-playing', 'strategy' ),
),
),
) );
if ( $games->have_posts() ) {
while ( $games->have_posts() ) {
$games->the_post();
the_title( '<h3>', '</h3>' );
}
}
wp_reset_postdata();This example asks for game posts associated with the selected term slugs. Keep the taxonomy key, post type key, and term slugs synchronized with the values stored in WordPress. After a custom loop, call wp_reset_postdata() so later template code returns to the main query.
Read terms assigned to one post
Use get_the_terms() when rendering a game’s assigned classifications. It returns the terms for the current post and taxonomy, allowing you to print names and archive links without hard-coding the term list.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall<?php
$genres = get_the_terms( get_the_ID(), 'game_genre' );
if ( $genres && ! is_wp_error( $genres ) ) {
echo '<ul class="game-genres">';
foreach ( $genres as $genre ) {
echo '<li>';
echo '<a href="' . esc_url( get_term_link( $genre ) ) . '">';
echo esc_html( $genre->name );
echo '</a>';
echo '</li>';
}
echo '</ul>';
}Check both the empty result and the error result before iterating. Escape URLs and visible term names when outputting them. This keeps the rendering layer separate from the taxonomy definition and makes the same taxonomy usable in cards, single templates, and navigation components.
Retrieve a term list for navigation or filters
For a directory, filter control, or landing page, retrieve terms directly with get_terms() and then link each term to its archive. Keep the selection rules in the query or template rather than duplicating term names in markup; editors can then add or rename terms without requiring a code change.
A complete setup workflow
- Model the classification. Write down what each term means, whether terms need parents, and which post type owns the relationship.
- Reserve the key. Keep it under 32 characters, use only permitted lowercase characters, numbers, dashes, or underscores, and check for collisions with existing identifiers and reserved query variables.
- Register on
init. Add the callback to a plugin or site-specific code location that loads on every request. - Configure the editor. Set labels,
show_ui, hierarchy, and optionallyshow_admin_column. - Configure REST access. Set
show_in_resttotruewhen block-editor or API access is required. - Choose URL rules. Set a rewrite slug and hierarchical behavior that match the public information architecture.
- Flush once. After changing rewrite settings, perform one controlled flush rather than flushing on every page load.
- Create terms. Add representative parent, child, or flat terms in the dashboard or through your chosen import/API process.
- Assign terms. Apply them to enough content to test one-term, multi-term, parent, and child cases.
- Build output. Add archive templates, term links, and taxonomy queries where visitors need the classification.
- Validate. Check the dashboard, editor, REST discovery, archive URLs, term links, and custom queries.
Validation and troubleshooting
The taxonomy does not appear for the intended post type
- Confirm that the object-type argument uses the exact registered post type key, not its plural label.
- Confirm that the registration callback is attached to
initand is actually loaded. - Check that the taxonomy key is spelled identically in registration, queries, templates, and REST checks.
- Ensure
show_uiis enabled if editors need a dashboard management screen.
The block editor or REST API cannot see it
- Set
show_in_resttotrue; public visibility alone does not guarantee REST exposure. - Inspect
/wp/v2/taxonomiesand look for the taxonomy slug, hierarchy flag, associated types, and route information. - Verify that the post type itself is configured for the editing workflow you are using.
The archive URL returns a 404
- Check the rewrite slug for spelling and collisions with another public path.
- Flush rewrite rules once after registration or a rewrite change.
- Confirm that the requested term exists in the taxonomy and that content is assigned to it.
Terms exist but no content is returned
- Use the taxonomy key, not the human-readable label, in
tax_query. - Check whether the query is using term IDs, names, or slugs and set the
fieldvalue accordingly. - Confirm that the queried post type matches the object type attached to the taxonomy.
The taxonomy key conflicts with another feature
Choose a new unique key rather than trying to work around a collision. The key is used by queries, URLs, and APIs, so a conflict can produce ambiguous or unpredictable behavior. If a taxonomy is already in use, plan any rename as a migration that updates code, stored assignments, links, and redirects rather than changing one string casually.
Keep the taxonomy maintainable
Document the purpose of each taxonomy and the rule for adding terms. A controlled vocabulary prevents near-duplicates such as two spellings of the same genre. For a hierarchical taxonomy, document what belongs at each level so editors do not create arbitrary depth. For a flat taxonomy, define whether terms are broad topics, precise filters, or both; mixing those roles makes navigation and queries harder to understand.
Keep presentation code out of the registration callback. The callback should define the taxonomy contract; templates, query functions, and blocks should decide how terms appear. This separation lets you change a card layout without changing the data model and makes it easier to expose the same terms through the dashboard, REST API, and front end.
Review public URLs before launch. A rewrite slug becomes part of your site’s address structure, and hierarchical paths communicate relationships to visitors. Select a stable vocabulary, test parent and child links, and flush rules only when the structure changes.
Quick Recap
Final verification checklist
- The taxonomy has a unique, valid key of no more than 32 characters.
- Registration runs on
init, never before it. - The object-type argument matches the intended post type key.
- Hierarchy reflects real parent-child relationships, or is disabled for independent terms.
- Labels describe the vocabulary clearly in the dashboard.
show_uiandshow_admin_columnmatch the editorial workflow.show_in_restis enabled when block-editor or REST access is required.- The rewrite slug and hierarchy match the public URL plan.
- Rewrite rules were flushed once after the relevant change, not on every request.
- Terms have been created, assigned, queried, and rendered in the intended templates.
- Taxonomy discovery confirms the slug, hierarchy, associated types, and REST route information.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
