Custom Taxonomies

Exposing Custom Taxonomies to GraphQL requires just 3 fields to be added to the Taxonomy registration.

  • show_in_graphql: true or false
  • graphql_single_name: camel case string with no punctuation or spaces
  • graphql_plural_name: camel case string with no punctuation or spaces

Register new Taxonomy

This is an example of registering a new “document_tag” Taxonomy to be connected to the "docs" Custom Post Type and enabling GraphQL support.

add_action('init', function() {
  register_taxonomy( 'doc_tag', 'docs', [
    'labels'  => [
        'menu_name' => __( 'Document Tags', 'your-textdomain' ),//@see
    'show_in_graphql' => true,
    'graphql_single_name' => 'DocumentTag',
    'graphql_plural_name' => 'DocumentTags',

Filtering existing Taxonomies

If you want to expose a Taxonomy that you don’t control the registration for, such as a taxonomy registered by a third-party plugin, you can filter the Taxonomy registration like so:

add_filter( 'register_taxonomy_args', function( $args, $taxonomy ) {

    if ( 'doc_tag' === $taxonomy ) {
        $args['show_in_graphql'] = true;
        $args['graphql_single_name'] = 'DocumentTag';
        $args['graphql_plural_name'] = 'DocumentTags';

    return $args;

}, 10, 2 );

Querying Custom Taxonomies

With just a few lines of code, our custom Taxonomy is added to the Schema in various places.

Below are some examples, but it’s probably worth exploring the Schema a bit to see where all your new Type shows up in the Schema.

Query a single Document Tag

This example shows how to query a single Document Tag by its ID.

  documentTag(id: "ZG9jX3RhZzo3") {

Query a DocumentTags on a Document

Since the doc_tags Custom Taxonomy has been registered in connection to the docs Post Type, our Schema automatically exposes a connection between Document nodes and DocumentTags.

query GetDocumentAndTags {
  documentBy(uri: "parent-slug/child-document-slug") {
    documentTags {
      nodes {