Taxonomy API Hooks

Actions and filters for the Taxonomy API.


Taxonomy Registration

registered_taxonomy

Fires after a taxonomy is registered.

do_action( 'registered_taxonomy', string $taxonomy, array|string $object_type, array $args )
ParameterTypeDescription
$taxonomystringTaxonomy slug
$object_typearray|stringObject type(s)
$argsarrayRegistration arguments

Example:

css
add_action( 'registered_taxonomy', function( $taxonomy, $object_type, $args ) {
    error_log( "Taxonomy registered: {$taxonomy}" );
}, 10, 3 );

registered_taxonomy_{$taxonomy}

Fires after a specific taxonomy is registered.

do_action( "registered_taxonomy_{$taxonomy}", string $taxonomy, array|string $object_type, array $args )
ParameterTypeDescription
$taxonomystringTaxonomy slug
$object_typearray|stringObject type(s)
$argsarrayRegistration arguments

Possible hook names: registered_taxonomy_category, registered_taxonomy_post_tag


unregistered_taxonomy

Fires after a taxonomy is unregistered.

do_action( 'unregistered_taxonomy', string $taxonomy )
ParameterTypeDescription
$taxonomystringTaxonomy name

registered_taxonomy_for_object_type

Fires after a taxonomy is registered for an object type.

do_action( 'registered_taxonomy_for_object_type', string $taxonomy, string $object_type )
ParameterTypeDescription
$taxonomystringTaxonomy name
$object_typestringObject type name

unregistered_taxonomy_for_object_type

Fires after a taxonomy is unregistered for an object type.

do_action( 'unregistered_taxonomy_for_object_type', string $taxonomy, string $object_type )
ParameterTypeDescription
$taxonomystringTaxonomy name
$object_typestringObject type name

register_taxonomy_args

Filters the arguments for registering a taxonomy.

apply_filters( 'register_taxonomy_args', array $args, string $taxonomy, string[] $object_type )
ParameterTypeDescription
$argsarrayRegistration arguments
$taxonomystringTaxonomy key
$object_typestring[]Object type names

Returns: Modified arguments array.

Example:

add_filter( 'register_taxonomy_args', function( $args, $taxonomy, $object_type ) {
    // Force all taxonomies to show in REST
    $args['show_in_rest'] = true;
    return $args;
}, 10, 3 );

register_{$taxonomy}_taxonomy_args

Filters the arguments for registering a specific taxonomy.

apply_filters( "register_{$taxonomy}_taxonomy_args", array $args, string $taxonomy, string[] $object_type )
ParameterTypeDescription
$argsarrayRegistration arguments
$taxonomystringTaxonomy key
$object_typestring[]Object type names

Possible hook names: register_category_taxonomy_args, register_post_tag_taxonomy_args

Returns: Modified arguments array.


taxonomy_labels_{$taxonomy}

Filters the labels of a specific taxonomy.

apply_filters( "taxonomy_labels_{$taxonomy}", object $labels )
ParameterTypeDescription
$labelsobjectLabels object

Returns: Modified labels object.


Term Retrieval

get_terms_defaults

Filters the terms query default arguments.

apply_filters( 'get_terms_defaults', array $defaults, string[] $taxonomies )
ParameterTypeDescription
$defaultsarrayDefault get_terms() arguments
$taxonomiesstring[]Taxonomy names

Returns: Modified defaults array.


get_terms_args

Filters the terms query arguments.

apply_filters( 'get_terms_args', array $args, string[] $taxonomies )
ParameterTypeDescription
$argsarrayQuery arguments
$taxonomiesstring[]Taxonomy names

Returns: Modified arguments array.


get_terms_fields

Filters the fields to select in the terms query.

apply_filters( 'get_terms_fields', string[] $selects, array $args, string[] $taxonomies )
ParameterTypeDescription
$selectsstring[]Fields to select
$argsarrayQuery arguments
$taxonomiesstring[]Taxonomy names

Returns: Modified selects array.


get_terms_orderby

Filters the ORDERBY clause of the terms query.

apply_filters( 'get_terms_orderby', string $orderby, array $args, string[] $taxonomies )
ParameterTypeDescription
$orderbystringORDERBY clause
$argsarrayQuery arguments
$taxonomiesstring[]Taxonomy names

Returns: Modified ORDERBY clause.


list_terms_exclusions

Filters the terms to exclude from the terms query.

apply_filters( 'list_terms_exclusions', string $exclusions, array $args, string[] $taxonomies )
ParameterTypeDescription
$exclusionsstringNOT IN clause
$argsarrayQuery arguments
$taxonomiesstring[]Taxonomy names

Returns: Modified exclusions SQL.


terms_clauses

Filters the terms query SQL clauses.

apply_filters( 'terms_clauses', string[] $clauses, string[] $taxonomies, array $args )
ParameterTypeDescription
$clausesstring[]SQL clauses (fields, join, where, distinct, orderby, order, limits)
$taxonomiesstring[]Taxonomy names
$argsarrayQuery arguments

Returns: Modified clauses array.


terms_pre_query

Filters the terms array before the query takes place.

apply_filters_ref_array( 'terms_pre_query', array $terms, WP_Term_Query &$query )
ParameterTypeDescription
$termsarray|nullReturn array to short-circuit, null to continue
$queryWP_Term_QueryQuery instance (by reference)

Returns: Array to short-circuit or null.


get_terms

Filters the found terms.

apply_filters( 'get_terms', array $terms, array|null $taxonomies, array $args, WP_Term_Query $term_query )
ParameterTypeDescription
$termsarrayFound terms
$taxonomiesarray|nullTaxonomy names
$argsarrayQuery arguments
$term_queryWP_Term_QueryQuery object

Returns: Modified terms array.


get_term

Filters a taxonomy term object.

apply_filters( 'get_term', WP_Term $_term, string $taxonomy )
ParameterTypeDescription
$_termWP_TermTerm object
$taxonomystringTaxonomy slug

Returns: Modified term object.


get_{$taxonomy}

Filters a taxonomy term object for a specific taxonomy.

apply_filters( "get_{$taxonomy}", WP_Term $_term, string $taxonomy )
ParameterTypeDescription
$_termWP_TermTerm object
$taxonomystringTaxonomy slug

Possible hook names: get_category, get_post_tag

Returns: Modified term object.


parse_term_query

Fires after term query vars have been parsed.

do_action( 'parse_term_query', WP_Term_Query $query )
ParameterTypeDescription
$queryWP_Term_QueryQuery instance

pre_get_terms

Fires before terms are retrieved.

php
do_action_ref_array( 'pre_get_terms', array( WP_Term_Query &$query ) )
ParameterTypeDescription
$queryWP_Term_QueryQuery instance (by reference)

Term Creation

pre_insert_term

Filters a term before it is sanitized and inserted into the database.

apply_filters( 'pre_insert_term', string|WP_Error $term, string $taxonomy, array|string $args )
ParameterTypeDescription
$termstring|WP_ErrorTerm name or error
$taxonomystringTaxonomy slug
$argsarray|stringArguments passed to wp_insert_term()

Returns: Term name or WP_Error to abort.


wp_insert_term_data

Filters term data before it is inserted into the database.

apply_filters( 'wp_insert_term_data', array $data, string $taxonomy, array $args )
ParameterTypeDescription
$dataarrayTerm data (name, slug, term_group)
$taxonomystringTaxonomy slug
$argsarrayArguments passed to wp_insert_term()

Returns: Modified data array.


wp_insert_term_duplicate_term_check

Filters the duplicate term check that takes place during term creation.

apply_filters( 'wp_insert_term_duplicate_term_check', object $duplicate_term, string $term, string $taxonomy, array $args, int $tt_id )
ParameterTypeDescription
$duplicate_termobjectDuplicate term row from database
$termstringTerm being inserted
$taxonomystringTaxonomy name
$argsarrayInsert arguments
$tt_idintTerm taxonomy ID of new term

Returns: Duplicate term object or null to skip check.


create_term

Fires immediately after a new term is created, before the term cache is cleaned.

do_action( 'create_term', int $term_id, int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayArguments passed to wp_insert_term()

create_{$taxonomy}

Fires after a new term is created for a specific taxonomy.

do_action( "create_{$taxonomy}", int $term_id, int $tt_id, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$argsarrayInsert arguments

Possible hook names: create_category, create_post_tag


term_id_filter

Filters the term ID after a new term is created.

apply_filters( 'term_id_filter', int $term_id, int $tt_id, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$argsarrayInsert/update arguments

Returns: Modified term ID.


created_term

Fires after a new term is created, and after the term cache has been cleaned.

do_action( 'created_term', int $term_id, int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayInsert arguments

created_{$taxonomy}

Fires after a new term in a specific taxonomy is created, and after the term cache has been cleaned.

do_action( "created_{$taxonomy}", int $term_id, int $tt_id, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$argsarrayInsert arguments

Possible hook names: created_category, created_post_tag


Term Update

edit_terms

Fires immediately before the given terms are edited.

do_action( 'edit_terms', int $term_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$taxonomystringTaxonomy slug
$argsarrayArguments passed to wp_update_term()

edited_terms

Fires immediately after a term is updated in the database, but before its term-taxonomy relationship is updated.

do_action( 'edited_terms', int $term_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

wp_update_term_parent

Filters the term parent.

apply_filters( 'wp_update_term_parent', int $parent_term, int $term_id, string $taxonomy, array $parsed_args, array $args )
ParameterTypeDescription
$parent_termintParent term ID
$term_idintTerm ID
$taxonomystringTaxonomy slug
$parsed_argsarrayParsed update arguments
$argsarrayOriginal arguments

Returns: Modified parent term ID.


wp_update_term_data

Filters term data before it is updated in the database.

apply_filters( 'wp_update_term_data', array $data, int $term_id, string $taxonomy, array $args )
ParameterTypeDescription
$dataarrayTerm data to update
$term_idintTerm ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

Returns: Modified data array.


edit_term_taxonomy

Fires immediately before a term-taxonomy relationship is updated.

do_action( 'edit_term_taxonomy', int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

edited_term_taxonomy

Fires immediately after a term-taxonomy relationship is updated.

do_action( 'edited_term_taxonomy', int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

edit_term

Fires after a term has been updated, but before the term cache has been cleaned.

do_action( 'edit_term', int $term_id, int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

edit_{$taxonomy}

Fires after a term in a specific taxonomy has been updated, but before the term cache has been cleaned.

do_action( "edit_{$taxonomy}", int $term_id, int $tt_id, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$argsarrayUpdate arguments

Possible hook names: edit_category, edit_post_tag


edited_term

Fires after a term has been updated, and the term cache has been cleaned.

do_action( 'edited_term', int $term_id, int $tt_id, string $taxonomy, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$argsarrayUpdate arguments

edited_{$taxonomy}

Fires after a term for a specific taxonomy has been updated, and the term cache has been cleaned.

do_action( "edited_{$taxonomy}", int $term_id, int $tt_id, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$argsarrayUpdate arguments

Possible hook names: edited_category, edited_post_tag


Saved Term (Both Create and Update)

saved_term

Fires after a term has been saved, and the term cache has been cleared.

do_action( 'saved_term', int $term_id, int $tt_id, string $taxonomy, bool $update, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$updateboolWhether this is an update
$argsarrayInsert/update arguments

saved_{$taxonomy}

Fires after a term in a specific taxonomy has been saved, and the term cache has been cleared.

do_action( "saved_{$taxonomy}", int $term_id, int $tt_id, bool $update, array $args )
ParameterTypeDescription
$term_idintTerm ID
$tt_idintTerm taxonomy ID
$updateboolWhether this is an update
$argsarrayInsert/update arguments

Possible hook names: saved_category, saved_post_tag


Term Deletion

pre_delete_term

Fires when deleting a term, before any modifications are made to posts or terms.

do_action( 'pre_delete_term', int $term, string $taxonomy )
ParameterTypeDescription
$termintTerm ID
$taxonomystringTaxonomy name

edit_term_taxonomies

Fires immediately before a term to delete’s children are reassigned a parent.

do_action( 'edit_term_taxonomies', array $edit_tt_ids )
ParameterTypeDescription
$edit_tt_idsarrayTerm taxonomy IDs of children

edited_term_taxonomies

Fires immediately after a term to delete’s children are reassigned a parent.

do_action( 'edited_term_taxonomies', array $edit_tt_ids )
ParameterTypeDescription
$edit_tt_idsarrayTerm taxonomy IDs of children

delete_term_taxonomy

Fires immediately before a term taxonomy ID is deleted.

do_action( 'delete_term_taxonomy', int $tt_id )
ParameterTypeDescription
$tt_idintTerm taxonomy ID

deleted_term_taxonomy

Fires immediately after a term taxonomy ID is deleted.

do_action( 'deleted_term_taxonomy', int $tt_id )
ParameterTypeDescription
$tt_idintTerm taxonomy ID

delete_term

Fires after a term is deleted from the database and the cache is cleaned.

do_action( 'delete_term', int $term, int $tt_id, string $taxonomy, WP_Term $deleted_term, array $object_ids )
ParameterTypeDescription
$termintTerm ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug
$deleted_termWP_TermDeleted term object
$object_idsarrayObject IDs that were assigned to term

delete_{$taxonomy}

Fires after a term in a specific taxonomy is deleted.

do_action( "delete_{$taxonomy}", int $term, int $tt_id, WP_Term $deleted_term, array $object_ids )
ParameterTypeDescription
$termintTerm ID
$tt_idintTerm taxonomy ID
$deleted_termWP_TermDeleted term object
$object_idsarrayObject IDs that were assigned

Possible hook names: delete_category, delete_post_tag


Object-Term Relationships

add_term_relationship

Fires immediately before an object-term relationship is added.

do_action( 'add_term_relationship', int $object_id, int $tt_id, string $taxonomy )
ParameterTypeDescription
$object_idintObject ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug

added_term_relationship

Fires immediately after an object-term relationship is added.

do_action( 'added_term_relationship', int $object_id, int $tt_id, string $taxonomy )
ParameterTypeDescription
$object_idintObject ID
$tt_idintTerm taxonomy ID
$taxonomystringTaxonomy slug

delete_term_relationships

Fires immediately before an object-term relationship is deleted.

do_action( 'delete_term_relationships', int $object_id, array $tt_ids, string $taxonomy )
ParameterTypeDescription
$object_idintObject ID
$tt_idsarrayTerm taxonomy IDs
$taxonomystringTaxonomy slug

deleted_term_relationships

Fires immediately after an object-term relationship is deleted.

do_action( 'deleted_term_relationships', int $object_id, array $tt_ids, string $taxonomy )
ParameterTypeDescription
$object_idintObject ID
$tt_idsarrayTerm taxonomy IDs
$taxonomystringTaxonomy slug

set_object_terms

Fires after an object’s terms have been set.

do_action( 'set_object_terms', int $object_id, array $terms, array $tt_ids, string $taxonomy, bool $append, array $old_tt_ids )
ParameterTypeDescription
$object_idintObject ID
$termsarrayTerm IDs or slugs
$tt_idsarrayTerm taxonomy IDs
$taxonomystringTaxonomy slug
$appendboolWhether appending to old terms
$old_tt_idsarrayPrevious term taxonomy IDs

wp_get_object_terms_args

Filters arguments for retrieving object terms.

apply_filters( 'wp_get_object_terms_args', array $args, int[] $object_ids, string[] $taxonomies )
ParameterTypeDescription
$argsarrayQuery arguments
$object_idsint[]Object IDs
$taxonomiesstring[]Taxonomy names

Returns: Modified arguments array.


get_object_terms

Filters the terms for a given object or objects.

apply_filters( 'get_object_terms', WP_Term[]|int[]|string[]|string $terms, int[] $object_ids, string[] $taxonomies, array $args )
ParameterTypeDescription
$termsarray|stringTerms or count
$object_idsint[]Object IDs
$taxonomiesstring[]Taxonomy names
$argsarrayQuery arguments

Returns: Modified terms.


wp_get_object_terms

Filters the terms for a given object or objects (legacy format).

apply_filters( 'wp_get_object_terms', WP_Term[]|int[]|string[]|string $terms, string $object_ids, string $taxonomies, array $args )
ParameterTypeDescription
$termsarray|stringTerms or count
$object_idsstringComma-separated object IDs
$taxonomiesstringSQL fragment of taxonomy names
$argsarrayQuery arguments

Returns: Modified terms.


Term Sanitization

edit_term_{$field}

Filters a term field to edit before it is sanitized.

apply_filters( "edit_term_{$field}", mixed $value, int $term_id, string $taxonomy )
ParameterTypeDescription
$valuemixedField value
$term_idintTerm ID
$taxonomystringTaxonomy slug

Returns: Modified value.


edit_{$taxonomy}_{$field}

Filters the taxonomy field to edit before it is sanitized.

apply_filters( "edit_{$taxonomy}_{$field}", mixed $value, int $term_id )
ParameterTypeDescription
$valuemixedField value
$term_idintTerm ID

Returns: Modified value.


pre_term_{$field}

Filters a term field value before it is sanitized for database.

apply_filters( "pre_term_{$field}", mixed $value, string $taxonomy )
ParameterTypeDescription
$valuemixedField value
$taxonomystringTaxonomy slug

Returns: Modified value.


pre_{$taxonomy}_{$field}

Filters a taxonomy field before it is sanitized for database.

apply_filters( "pre_{$taxonomy}_{$field}", mixed $value )
ParameterTypeDescription
$valuemixedField value

Returns: Modified value.


term_{$field}

Filters the term field sanitized for display.

apply_filters( "term_{$field}", mixed $value, int $term_id, string $taxonomy, string $context )
ParameterTypeDescription
$valuemixedField value
$term_idintTerm ID
$taxonomystringTaxonomy slug
$contextstringDisplay context

Returns: Modified value.


{$taxonomy}_{$field}

Filters the taxonomy field sanitized for display.

apply_filters( "{$taxonomy}_{$field}", mixed $value, int $term_id, string $context )
ParameterTypeDescription
$valuemixedField value
$term_idintTerm ID
$contextstringDisplay context

Returns: Modified value.


Term Slugs

wp_unique_term_slug_is_bad_slug

Filters whether the proposed unique term slug is bad.

apply_filters( 'wp_unique_term_slug_is_bad_slug', bool $needs_suffix, string $slug, object $term )
ParameterTypeDescription
$needs_suffixboolWhether slug needs suffix
$slugstringProposed slug
$termobjectTerm object

Returns: Whether to add suffix.


wp_unique_term_slug

Filters the unique term slug.

apply_filters( 'wp_unique_term_slug', string $slug, object $term, string $original_slug )
ParameterTypeDescription
$slugstringUnique slug
$termobjectTerm object
$original_slugstringOriginal proposed slug

Returns: Modified slug.


Filters the permalink structure for a term before token replacement occurs.

apply_filters( 'pre_term_link', string $termlink, WP_Term $term )
ParameterTypeDescription
$termlinkstringPermalink structure
$termWP_TermTerm object

Returns: Modified permalink structure.


Filters the term link.

apply_filters( 'term_link', string $termlink, WP_Term $term, string $taxonomy )
ParameterTypeDescription
$termlinkstringTerm link URL
$termWP_TermTerm object
$taxonomystringTaxonomy slug

Returns: Modified URL.


Filters the tag link (for post_tag taxonomy).

apply_filters( 'tag_link', string $termlink, int $term_id )
ParameterTypeDescription
$termlinkstringTag link URL
$term_idintTerm ID

Returns: Modified URL.


Filters the category link.

apply_filters( 'category_link', string $termlink, int $term_id )
ParameterTypeDescription
$termlinkstringCategory link URL
$term_idintTerm ID

Returns: Modified URL.


Term Counting

update_term_count

Fires when a term count is calculated, before it is updated in the database.

do_action( 'update_term_count', int $tt_id, string $taxonomy_name, int $count )
ParameterTypeDescription
$tt_idintTerm taxonomy ID
$taxonomy_namestringTaxonomy slug
$countintTerm count

update_post_term_count_statuses

Filters the post statuses for updating the term count.

apply_filters( 'update_post_term_count_statuses', string[] $post_statuses, WP_Taxonomy $taxonomy )
ParameterTypeDescription
$post_statusesstring[]Post statuses to include
$taxonomyWP_TaxonomyTaxonomy object

Returns: Modified post statuses array.


Caching

clean_term_cache

Fires once after each taxonomy’s term cache has been cleaned.

do_action( 'clean_term_cache', array $ids, string $taxonomy, bool $clean_taxonomy )
ParameterTypeDescription
$idsarrayTerm IDs
$taxonomystringTaxonomy slug
$clean_taxonomyboolWhether taxonomy-wide caches were cleaned

clean_object_term_cache

Fires after the object term cache has been cleaned.

do_action( 'clean_object_term_cache', array $object_ids, string $object_type )
ParameterTypeDescription
$object_idsarrayObject IDs
$object_typestringObject type

clean_taxonomy_cache

Fires after a taxonomy’s caches have been cleaned.

do_action( 'clean_taxonomy_cache', string $taxonomy )
ParameterTypeDescription
$taxonomystringTaxonomy slug

Hierarchy

get_ancestors

Filters a given object’s ancestors.

apply_filters( 'get_ancestors', int[] $ancestors, int $object_id, string $object_type, string $resource_type )
ParameterTypeDescription
$ancestorsint[]Ancestor IDs
$object_idintObject ID
$object_typestringObject type
$resource_typestring'post_type' or 'taxonomy'

Returns: Modified ancestors array.


Split Terms

split_shared_term

Fires after a previously shared taxonomy term is split into two separate terms.

do_action( 'split_shared_term', int $term_id, int $new_term_id, int $term_taxonomy_id, string $taxonomy )
ParameterTypeDescription
$term_idintFormerly shared term ID
$new_term_idintNew term ID
$term_taxonomy_idintTerm taxonomy ID
$taxonomystringTaxonomy slug

Term Exists

term_exists_default_query_args

Filters default query arguments for checking if a term exists.

apply_filters( 'term_exists_default_query_args', array $defaults, int|string $term, string $taxonomy, int|null $parent_term )
ParameterTypeDescription
$defaultsarrayDefault get_terms() arguments
$termint|stringTerm to check
$taxonomystringTaxonomy name
$parent_termint|nullParent term ID

Returns: Modified defaults array.