How to Use tax_query in WordPress for Custom Taxonomy Queries

Use the tax_query parameter inside WP_Query to filter posts by taxonomy terms in WordPress. It accepts an array of conditions specifying taxonomy, terms, and operator to customize your query results.

Syntax

The tax_query parameter is an array of arrays, where each inner array defines a taxonomy filter. Key parts include:

• taxonomy: The taxonomy name (e.g., 'category', 'post_tag', or custom taxonomy).
• field: The field to filter by ('term_id', 'slug', or 'name').
• terms: The term or terms to match.
• operator: How to compare terms ('IN', 'NOT IN', 'AND').
• relation: (optional) How multiple taxonomies combine ('AND' or 'OR').

php

array(
  'tax_query' => array(
    'relation' => 'AND', // Optional: 'AND' or 'OR'
    array(
      'taxonomy' => 'taxonomy_name',
      'field'    => 'slug', // or 'term_id', 'name'
      'terms'    => array('term1', 'term2'),
      'operator' => 'IN' // or 'NOT IN', 'AND'
    ),
    // Add more arrays for multiple taxonomies
  )
)

Example

This example shows how to query posts that belong to the 'news' category and have the tag 'featured'. It uses tax_query with two conditions combined by 'AND'.

php

<?php
$args = array(
  'post_type' => 'post',
  'tax_query' => array(
    'relation' => 'AND',
    array(
      'taxonomy' => 'category',
      'field'    => 'slug',
      'terms'    => array('news'),
      'operator' => 'IN',
    ),
    array(
      'taxonomy' => 'post_tag',
      'field'    => 'slug',
      'terms'    => array('featured'),
      'operator' => 'IN',
    ),
  ),
);
$query = new WP_Query($args);

if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    echo '<h2>' . get_the_title() . '</h2>';
  }
} else {
  echo 'No posts found.';
}
wp_reset_postdata();
?>

Output

<h2>Post Title 1</h2><h2>Post Title 2</h2>... or No posts found.

Common Pitfalls

Common mistakes when using tax_query include:

• Not setting relation when using multiple taxonomies, causing unexpected results.
• Using incorrect field values like 'id' instead of 'term_id'.
• Passing a string instead of an array for terms when multiple terms are needed.
• Forgetting to reset post data after custom queries with wp_reset_postdata().

php

<?php
// Wrong: Using 'id' instead of 'term_id' and string instead of array for multiple terms
$args_wrong = array(
  'tax_query' => array(
    array(
      'taxonomy' => 'category',
      'field'    => 'id', // Incorrect
      'terms'    => array('news', 'updates'), // Should be array
    ),
  ),
);

// Correct:
$args_right = array(
  'tax_query' => array(
    array(
      'taxonomy' => 'category',
      'field'    => 'term_id',
      'terms'    => array(12, 34),
      'operator' => 'IN',
    ),
  ),
);
?>

Quick Reference

Parameter	Description	Example Values
taxonomy	Name of the taxonomy to query	'category', 'post_tag', 'custom_tax'
field	Field to filter by	'term_id', 'slug', 'name'
terms	Term or array of terms to match	'news', ['news', 'updates']
operator	Comparison operator	'IN', 'NOT IN', 'AND'
relation	Relation between multiple tax queries	'AND', 'OR'

Key Takeaways

Use tax_query inside WP_Query to filter posts by taxonomy terms.

Always specify taxonomy, field, terms, and optionally operator in each tax query array.

Use relation to combine multiple taxonomy queries logically with 'AND' or 'OR'.

Pass terms as an array when filtering by multiple terms and use correct field names like 'term_id' or 'slug'.

Reset post data with wp_reset_postdata() after custom queries to avoid conflicts.