What is a Term Meta in WordPress?

Term Meta in WordPress is a way to store custom metadata for taxonomy terms. This includes categories, tags, and terms in custom taxonomies. Introduced in WordPress 4.4, this feature lets developers add and retrieve extra data tied to specific terms. The data can be text, numbers, colors, images, or any other type of structured or simple content.

How It Works

Term Meta works like the metadata systems for posts, users, and comments. It uses a dedicated database table called termmeta to store each piece of data. This table includes:

meta_id: A unique ID for each row
term_id: The ID of the related term
meta_key: The identifier of the data
meta_value: The stored data

This setup allows for scalable and organized storage of custom fields for taxonomy terms.

Core Functions

WordPress provides functions to manage term meta. These are:

add_term_meta( $term_id, $meta_key, $meta_value, $unique ): Adds metadata to a term. If $unique is set to true, the combination of term ID and key must be unique.
update_term_meta( $term_id, $meta_key, $meta_value ): Updates an existing term meta key or creates it if it doesn’t exist.
get_term_meta( $term_id, $meta_key, $single ): Retrieves a term’s metadata. If $single is true, a single value will be returned.
delete_term_meta( $term_id, $meta_key, $meta_value ): Deletes one or more pieces of metadata from a term. You can also specify a specific value to delete.

All functions accept a term ID as the first parameter and affect the relevant taxonomy term.

Example: Adding and Using Term Meta

Here’s how to manage a term’s metadata programmatically.

php
// Add a term meta value
add_term_meta( $term_id, 'hex_color', '#ff0000' );
// Update the same meta key
update_term_meta( $term_id, 'hex_color', '#00ff00' );
// Get the value
$color = get_term_meta( $term_id, 'hex_color', true );
// Delete the value
delete_term_meta( $term_id, 'hex_color' );

These are standard PHP functions in the WordPress core and can be added to a plugin, theme, or custom script.

Database Structure

Term Meta uses a separate table from posts or users. The table is named wp_termmeta by default (with wp_ being the common prefix). This helps reduce clutter in the wp_options table, unlike in earlier versions where developers stored extra data in options or custom tables.

Use with Custom Taxonomies

You can use term meta functions with any taxonomy, including ones created using register_taxonomy(). For example, if you create a taxonomy called house_feature, you can set and retrieve term meta for each feature.

php
$term_id = 43; // A term in the house_feature taxonomy
add_term_meta( $term_id, 'icon_class', 'icon-fireplace' );

This enhances flexibility when building tailored features into a theme or plugin.

Use Cases

Here are common examples of how term meta can be applied:

Storing icons or color codes for terms
Linking terms to external resources or media
Grouping or tagging terms using hidden fields
Mapping visual data to tag archives, such as showing a background image per category
Filtering and querying terms based on stored meta values

These features help in controlling both the behavior and visual output of taxonomy-related pages.

Querying by Term Meta

Developers can filter or sort terms based on metadata using the get_terms() function with a meta_query parameter. This is useful when fetching terms that meet certain criteria.

php
$terms = get_terms( array(
    'taxonomy' => 'house_feature',
    'meta_query' => array(
        array(
            'key'   => 'icon_class',
            'value' => 'icon-fireplace',
        ),
    ),
) );

his works similarly to querying posts with WP_Query.

Displaying Term Meta in Admin Columns

You can make custom metadata visible in the WordPress dashboard by modifying list columns in term management pages.

php
function add_term_meta_column( $columns ) {
    $columns['hex_color'] = 'Color';
    return $columns;
}
add_filter( 'manage_edit-house_feature_columns', 'add_term_meta_column' );
function show_term_meta_column( $value, $column, $term_id ) {
    if ( 'hex_color' === $column ) {
        return get_term_meta( $term_id, 'hex_color', true );
    }
    return $value;
}
add_filter( 'manage_house_feature_custom_column', 'show_term_meta_column', 10, 3 );

This allows a quick reference of metadata directly from the backend interface.

WP-CLI Integration

From the command line, WP-CLI can be used to add, get, update, and delete term meta.

“`bash

Set the term meta

wp term meta set 25 icon “heart-icon”

Get the term meta

wp term meta get 25 icon

Update the value

wp term meta update 25 icon “checkmark-icon”

Delete the meta key

wp term meta delete 25 icon
“`

These commands run directly through terminal and provide developers with an efficient way to automate changes across environments.

Backward Compatibility

Before WordPress 4.4, there was no direct method for handling term metadata. Developers had to duplicate functionality with the wp_options table or other workarounds. If supporting older WordPress versions, it is necessary to check the running version and use alternate logic.

php
if ( version_compare( get_bloginfo( 'version' ), '4.4', '<' ) ) {
    // Fallback logic for older versions
}

This keeps code stable on websites that haven’t been updated to newer versions.

Plugin Support

There are plugins that allow site admins to manage term meta without writing code. Some plugins offer field builders and graphical interfaces. These can help to:

Create repeatable fields
Restrict input types
Assign fields to specific taxonomies
Show inputs when editing existing terms

This makes content management easier for non-technical users.

Grouping and Filtering Terms

Term meta can also be used to maintain logical or visual groupings between term objects. For example, in a taxonomy like house_feature, each term could store a group ID or name.

php
add_term_meta( $term_id, 'group_id', 'premium_features' );

Then, when rendering, this field can be used to organize output without creating another taxonomy or hierarchy.