/

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.

Queries

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.

GraphiQL Loading...

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

GraphiQL Loading...

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.

GraphiQL Loading...

The same can be done with categories:

GraphiQL Loading...

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:

GraphiQL Loading...

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

This can be done like so:

GraphiQL Loading...
More info on this featureFor more info on how this type of query works, see the details here

Mutations

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

PostObjects can also be associated with Categories and Tags.

Mutations and AuthWPGraphQL 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 Loading...

Create Category

This is an example of creating a category:

GraphiQL Loading...

Update Tag

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

This is an example of updating a tag:

GraphiQL Loading...

Update Category

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

This is an example of updating a category:

GraphiQL Loading...

Delete Tag

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

This is an example of deleting a tag:

GraphiQL Loading...

Delete Category

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

This is an example of deleting a category:

GraphiQL Loading...

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 Loading...
Edit on GitHub