Skip to main content

Term Queries

Query WordPress taxonomy terms for category listings, tag clouds, and taxonomy-based navigation.

What This Guide Covers​

Terms are WordPress taxonomy data - categories, tags, and custom taxonomies that organize your content. This guide shows you how to query WordPress terms using Builderius GraphQL for any taxonomy scenario.

You'll learn how to:

  • Get current term data for archive templates
  • Query multiple terms for category listings and tag clouds
  • Filter terms by taxonomy, post counts, and custom criteria
  • Access custom term fields from ACF and MetaBox
  • Build taxonomy-based navigation and filtering
  • Handle term pagination and hierarchical relationships

Query Single Term​

Get the term you're currently viewing (on category/tag archives):

{
  archive {
    term {
      term_id
      name
      slug
      description
      count
    }
  }
}

Term ID vs Term Taxonomy ID​

Normal WordPress Behavior (Separate Terms): When you create terms through wp-admin, each taxonomy gets its own separate terms (php code serves as explanation):

// Create "News" as category - gets term_id = 5, term_taxonomy_id = 10
wp_insert_term('News', 'category');

// Create "News" as tag - gets term_id = 6, term_taxonomy_id = 11  
wp_insert_term('News', 'post_tag');

In this normal case, term_id and term_taxonomy_id are functionally equivalent for querying.

Complete Term Fields Reference​

Here's what's available when querying a term - all standard WordPress taxonomy fields plus custom field integrations:

{
  term {
    # Basic Fields
    term_id
    name
    slug
    term_group
    term_taxonomy_id
    taxonomy
    description
    count
    parent
    
    # Children Terms (Hierarchy)
    children {
      term_id
      name
      slug
      count
    }
    
    # Native WordPress Meta Fields
    featured_color: meta_value(key: "_featured_color")
    custom_icon: meta_value(key: "_custom_icon")
    
    # All Meta Fields (returns array)
    meta {
      key
      value
    }
    
    # ACF Fields
    category_image: acf_value(name: "category_image")
    featured_on_homepage: acf_value(name: "featured_on_homepage")
    category_color: acf_value(name: "category_color")
    description_extended: acf_value(name: "description_extended")
    
    # ACF Repeater Fields
    featured_posts: acf_repeater_value(name: "featured_posts") {
      post_id: acf_value(name: "post_id")
      featured_order: acf_value(name: "featured_order")
    }
    
    # MetaBox Fields (Term Level)
    category_priority: metabox_value(field_id: "category_priority")
    display_settings: metabox_value(field_id: "display_settings")
  }
}

Basic Term Loop​

{
  terms_query(
    arguments: {
      taxonomy: "category"
      hide_empty: true
      number: 10
    }
  ) {
    terms {
      term_id
      name
      slug
      description
      count
    }
  }
}

Custom Term Queries​

Custom term queries Pro feature let you manually specify exactly what terms you want, with your own filtering and arguments. You have complete control over which terms to display and how they're organized.

Category listings with post counts:

{
  terms_query(
    arguments: {
      taxonomy: "category"
      hide_empty: true
      number: 15
      orderby: "name"
      order: "ASC"
    }
  ) {
    terms {
      term_id
      name
      slug
      description
      count
      parent
    }
    pagination {
      links
    }
  }
}

Query Arguments​

Complete Arguments Reference​

All arguments available for terms_query shown in context:

{
  terms_query(
    arguments: {
      # Taxonomy
      taxonomy: "category"         # String or Array of strings - Taxonomy name (category, post_tag, or custom taxonomy)
      
      # Include/Exclude Terms
      include: [1, 5, 12]          # Array - Include only these term IDs
      exclude: [3, 7]              # Array - Exclude these term IDs
      
      # Filter Options
      hide_empty: true             # Boolean - Hide terms with no posts (true, false)
      object_ids: [10, 25, 30]     # Array - Filter terms by object/post IDs
      name: ["News", "Updates"]    # Array - Filter by term names
      slug: ["news", "updates"]    # Array - Filter by term slugs
      
      # Pagination & Limits
      number: 20                   # Int - Number of terms to return
      offset: 5                    # Int - Number of terms to skip from start
      
      # Ordering
      orderby: "name"              # String - Sort field (name, slug, term_group, term_id, description, count)
      order: "ASC"                 # String - Sort direction (ASC, DESC)
    }
  ) {
    terms {
      name
      slug
    }
  }
}

Basic Filtering​

Filter by specific taxonomy:

{
  terms_query(
    arguments: {
      taxonomy: "category"
    }
  ) {
    terms {
      name
      slug
    }
  }
}

Term to Term Relationships​

Navigate between related terms using hierarchical and sibling relationships.

Get parent term of the current term:

{
  archive {
    term {
      name
      parent @private                    # Get parent ID for conditionals
      parent_data: terms_query(          # Fetch parent term details
        arguments: {
          taxonomy: "category"  
          include: "{{parent}}"
        }
      ) @private {
        terms {
          term_id @private
          name
        }
      }
      parent_is: expression_result(
        expression: "(parent > 0) ? parent_data.terms[0].name : null"  # Show parent name or null
      )
    }
  }
}

Content Relationships​

Connect terms with their associated posts and content.

Get terms for the current post:

{
  post {
    ID @private
    post_categories: terms_query(
      arguments: {
        taxonomy: "category"
        object_ids: "{{ID}}"     # Terms assigned to current post
      }
    ) {
      terms {
        name
        slug
        count
      }
    }
  }
}

Pagination​

Handle pagination for term listings with custom URL parameters.

Basic term pagination:

{
  terms_query(
    arguments: {
      taxonomy: "category"
      hide_empty: true
      number: 20
      orderby: "name"
      order: "ASC"
    }
  ) {
    terms {
      name
      slug
      count
    }
    pagination(
      arguments: {
        pagination_url_param_name: "category_page"
      }
    ) {
      links
      current_page
      total_pages
    }
  }
}

Performance Tips​

Optimize your term queries for better performance by using these techniques.

Use @private to query data you need for variables but don't want in output:

{
  archive {
    term {
      term_id @private                 # Hidden from output, available for {{term_id}}
      name
      parent_category: terms_query(
        arguments: {
          taxonomy: "category"
          include: "{{parent}}"      # Uses private parent field
        }
      ) {
        terms {
          name
          slug
        }
      }
    }
  }
}

Common Use Cases​

Real-world examples of term queries you'll commonly need for category listings, tag clouds, and taxonomy navigation.

Category navigation with hierarchy and custom images:

{
  terms_query(
    arguments: {
      taxonomy: "category"
      parent: 0                        # Top-level categories only
      hide_empty: true                 # Only categories with posts
      orderby: "name"
      order: "ASC"
    }
  ) {
    terms {
      term_id
      name
      slug
      count
      # ACF fields for navigation
      category_image: acf_value(name: "category_image")
      featured_on_nav: acf_value(name: "featured_on_nav")
      nav_color: acf_value(name: "nav_color")
      # Child categories
      subcategories: terms_query(
        arguments: {
          taxonomy: "category"
          parent: "{{term_id}}"        # Children of this category
          hide_empty: true
          number: 10
          orderby: "name"
          order: "ASC"
        }
      ) {
        terms {
          name
          slug
          count
        }
      }
    }
  }
}