Custom Tags

We can add tags to posts in WordPress (i.e. using the taxonomy with name "post_tag"). This is already mapped in the GraphQL schema via the PostTag type, associated to a Post entry.

Likewise, a custom post type, defined by any theme or plugin (such as "product"), can have its own taxonomy tag associated to it (such as "product-cat"). As these custom post types are not mapped to the GraphQL schema, they are resolved via type GenericCustomPost, and their tags are resolved as GenericTag.

We use fields tag and tags to fetch tag data, which must indicate which taxonomy they refer to via mandatory field argument taxonomy. The result is of the union type TagUnion, which includes entries from either PostTag or GenericTag (depending on the entry's taxonomy).

For instance, this query retrieves tags with taxonomy "product-tag":

{
  tags(taxonomy: "product-tag") {
    __typename

    ...on Tag {
      count
      description
      id
      name
      slug
      url
    }
    
    ...on GenericTag {
      taxonomy   
      customPostCount
      customPosts {
        __typename
        ...on CustomPost {
          id
          title
        }
      }
    }
  }
}

Allowing access to unmapped tag taxonomies

The tag taxonomies accessible via the GenericTag type must be explicitly configured in the plugin Settings page, as explained in guide Adding a custom tag taxonomy to the schema.

Retrieving tags associated to a custom post

Type GenericCustomPost has field tags, to retrieve the custom tags added to the custom post:

{
  customPosts(
    filter: { customPostTypes: "product" }
  ) {
    __typename

    ... on GenericCustomPost {
      tags(taxonomy: "product-tag") {
        __typename
        id
        name
        taxonomy
      }
    }
  }
}

Filtering custom posts by tag

To retrieve the custom posts with a given tag or tags, we can use inputs filter.tagIDs or filter.tagSlugs and filter.tagTaxonomy:

{
  customPostsByTagIDs: customPosts(
    filter: {
      tagIDs: [26, 28],
      tagTaxonomy: "product-tag"
    }
  ) {
    id
    title
  }

  customPostsByTagSlugs: customPosts(
    filter: {
      tagSlugs: ["tango", "rock"],
      tagTaxonomy: "product-tag"
    }
  ) {
    id
    title
  }
}