Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
389 lines (330 sloc) 7.89 KB
title description
Categories and Tags
Learn how to interact with Categories and Tags using WPGraphQL

Categories and Tags are core Taxonomy Types in WordPress and allow content to be grouped. Each individual Category or Tag is known as a "Term".

Terms are exposed to the WPGraphQL Schema by default. On this page are some examples of interacting with Categories and Tags using WPGraphQL.

If any of the terminology or semantics of the GraphQL queries/mutations on this page are confusing, check out the Intro to GraphQL Guide to get more familiar with the basics.


WPGraphQL comes with RootQuery fields built-in to query Tags and Categories. You can query for lists of Terms, an individual term, and even Post Objects related to Terms.

List Of Tags

In this example, we query a list of Tag nodes. By default, WPGraphQL will return 10 items.

In this example, we query a list of Category nodes. By default, WPGraphQL will return 10 items.

Related Objects

Tags are associated with Posts (and possibly other Post Types). Any Post Type that is registered to be connected with Tags can be queried for as a connection to tags.

Below is an example of asking for a list of Tags, and on each Tag, a list of posts it's connected to.

The same can be done with categories:

Hierarchical Taxonomies

One key difference between Tags and Categories is that Categories are hierarchical, meaning they can have parents and children.

When querying Categories, by default only the top level categories that are not children of another term are returned.

The children of those categories can be queried like so:

Sometimes, it makes sense to query for all categories regardless of their parent.

This can be done like so:

For more info on how this type of query works, see the details here


Categories and Tags can also be created, updated and deleted via GraphQL mutations.

PostObjects can also be associated with Categories and Tags.

WPGraphQL respects user capabilities when mutating data, so _most_ mutations in WPGraphQL require requests to be Authenticated, and the user making the request must have proper capabilities to mutate the data. Check out the Authentication and Authorization Guide to learn more.

The demos below are public requests and will not actually mutate data, but you can get an idea of how to compose mutations by looking at the examples.

Create Tag

This is an example of creating a tag:

<GraphiQL query=' mutation CREATE_TAG($input: CreateTagInput!) { createTag(input: $input) { tag { id } } } ' variables={ { input: { "clientMutationId": "CreateTag", "name": "New Tag" } } } />

Create Category

This is an example of creating a category:

<GraphiQL query=' mutation CREATE_TAG($input: CreateCategoryInput!) { createCategory(input: $input) { category { id } } } ' variables={ { input: { "clientMutationId": "CreateCategory", "name": "New Category" } } } />

Update Tag

In order to update a Tag, you must pass the ID.

This is an example of updating a tag:

<GraphiQL query=' mutation UPDATE_TAG($input: UpdateTagInput!) { updateTag(input: $input) { tag { id } } } ' variables={ { input: { "clientMutationId": "UpdateTag", "id": "cG9zdF90YWc6OA==", "description": "Updated Description..." } } } />

Update Category

In order to update a Category, you must pass the ID.

This is an example of updating a category:

<GraphiQL query=' mutation UPDATE_CATEGORY($input: UpdateCategoryInput!) { updateCategory(input: $input) { category { id } } } ' variables={ { input: { "clientMutationId": "UpdateCategory", "id": "cG9zdF90YWc6OA==", "description": "Updated Description..." } } } />

Delete Tag

In order to delete a Tag, you must pass the ID.

This is an example of deleting a tag:

<GraphiQL query=' mutation DELETE_TAG($input: DeleteTagInput!) { deleteTag(input:$input) { deletedId } } ' variables={ { input: { "clientMutationId": "DeleteTag", "id": "cG9zdF90YWc6OA==" } } } />

Delete Category

In order to delete a Category, you must pass the ID.

This is an example of deleting a category:

<GraphiQL query=' mutation DELETE_CATEGORY($input: DeleteCategoryInput!) { deleteCategory(input:$input) { deletedId } } ' variables={ { input: { "clientMutationId": "DeleteCategory", "id": "cG9zdF90YWc6OA==" } } } />

Add Tag to Post

This is an example of a mutation to update a Post and add a tag to it.

Here we pass the ID of the Post we want to update, and an array of Tag nodes we want to append to the Post. We can use tag names or tag IDs to attach to posts.

You can also attach terms in the createPost mutation.

<GraphiQL query=' mutation ADD_TAG_TO_POST($input: UpdatePostInput!) { updatePost(input: $input) { post { id title tags { nodes { id name } } } } } ' variables={ { "input": { "clientMutationId": "UpdatePost", "id": "cG9zdDoxMzY0", "tags": { "append": true, "nodes": [ { "name": "New Tag" } ] } } } } />

You can’t perform that action at this time.