Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get term by


Get all Term data from database by Term field and data.

Warning: $value is not HTML-escaped for the 'name' $field. You must do it yourself, if required.

The default $field is 'id', therefore, it is possible to also use null for field, but not recommended that you do so.

If $value does not exist, the return value will be false. If $taxonomy exists and $field and $value combinations exist, the Term will be returned.


<?php get_term_by$field$value$taxonomy$output$filter ?>


(string) (required) Either 'id', 'slug', 'name', or 'term_taxonomy_id'
Default: 'id'
(string|integer) (required) Search for this term value
Default: None
(string) (required) Taxonomy Name category, post_tag, link_category, nav_menu or something custom
Default: None
(string) (optional) Constant OBJECT, ARRAY_A, or ARRAY_N
Default: OBJECT
(string) (optional) default is raw or no WordPress defined filter will applied.
Default: 'raw'

Return Values

Term Row (object or array) from database. Will return false if $taxonomy does not exist or $term was not found. Othewise returns object (by default) or array of fields depending on $output parameter.

The fields returned are:

  • term_id (See warning below)
  • name
  • slug
  • term_group
  • term_taxonomy_id
  • taxonomy
  • description
  • parent
  • count

Warning: string vs integer confusion! Field values, including term_id are returned in string format. Before further use, typecast numeric values to actual integers, otherwise WordPress will mix up term_ids and slugs which happen to have only numeric characters!


Taxonomy_name is the name of taxonomy, not the term_name and is required; the id (term_id) is the ID of the term, not post_id;...

↓ Taxonomy type (e.g. post_tag)
Terms in this taxonomy:
→ news
→ webdev
→ ...

Examples to get terms by name and taxonomy type (taxonomy_name as category, post_tag or custom taxonomy).

// Get term by name ''news'' in Categories taxonomy.
$category = get_term_by('name', 'news', 'category')

// Get term by name ''news'' in Tags taxonomy.
$tag = get_term_by('name', 'news', 'post_tag')

// Get term by name ''news'' in Custom taxonomy.
$term = get_term_by('name', 'news', 'my_custom_taxonomy')

// Get term by name ''Default Menu'' from theme's nav menus.
// (Alternative to using wp_get_nav_menu_items)
$menu = get_term_by('name', 'Default Menu', 'nav_menu');

By id (term_id, not post_id):

// Get term by id (''term_id'') in Categories taxonomy.
get_term_by('id', 12, 'category')


Wrong example in this page history

Warning: the example below is wrong (see in this page history):

get_term_by( 'id', (int) $post->ID, 'taxonomy_name' ); // return null

This example tries to get a term by ID (term_id) but uses a post ID instead of a term ID.

This example is the correct way to get the term(s) for a post using the post ID:

// get_term_by( 'id', $category_id, 'category' )
global $post;

$my_categories   = array();
$post_categories = get_the_category( $post->ID );

foreach ( $post_categories as $post_category ) {
	$my_categories[] = get_term_by( 'id', $post_category->cat_ID, 'category' );

// OR:
$my_category = get_term_by( 'id', $post_categories[0]->cat_ID, 'category' );


  • Warning: $value is not escaped for 'name' $field. You must do it yourself, if required.
  • See sanitize_term_field() The $context param lists the available values for 'get_term_by' $filter param.
  • Uses: sanitize_term() Cleanses the term based on $filter context before returning.
  • Uses global: (object) $wpdb

Change Log

Since: 2.3.0

Source File

get_term_by() is located in wp-includes/taxonomy.php.


See also index of Function Reference and index of Template Tags.