NEW! WPGraphQL for Advanced Custom Fields

Interact with ACF Field data using GraphQL Queries

Release v0.3.5

Today we released v0.3.5 of WPGraphQL.

Full release notes here:

WPGraphiQL IDE v1.0.0 with GraphQL Explorer

The GraphiQL IDE is an incredibly helpful tool when using GraphQL. WPGraphiQL has been the go-to GraphiQL IDE for use with WPGraphQL, and today we’ve released v1.0.0 of the WPGraphiQL IDE, now with the AMAZING GraphQL Explorer feature, courtesy of the fine folks at

WPGraphQL and Gatsby Livestream

Last week I joined Jason Lengstorf on “Learn with Jason” and we built a Gatsby site using WordPress, WPGraphQL and WPGraphQL for Advanced Custom Fields.

Below is a recording of the livestream.

Re-introducing WPGraphQL for ACF


Starting today, WPGraphQL for Advanced Custom Fields is FREE!

Some Context

In April 2019, I released the WPGraphQL for Advanced Custom Fields plugin as a paid plugin in an attempt to generate enough revenue to one day be able to work on WPGraphQL full-time.

I want to thank everyone that purchased a license and helped me grow the community. The purchases proved that this is an important plugin with an audience, and the revenue from the purchases have allowed me to spend time working on additional features, bug fixes, and interact with users in Slack, Twitter and other communication channels over the past few months. It’s clear that a big part of the future of WordPress headless, and WPGraphQL is a big part of that future.

New Opportunity

As you may have heard on or WPTavern, I have been blessed with the opportunity to join the Gatsby team, where I get to spend my time working on WPGraphQL and its immediate ecosystem, including plugins like WPGraphQL for Advanced Custom Fields.

Now that I have the opportunity to work on the WPGraphQL ecosystem full-time, the Gatsby team and I believe it’s best for the community to make the WPGraphQL for Advanced Custom Fields FREE, starting today.

The plugin is now freely available on Github: The plugin will also be submitted to which will allow the plugin to be more easily included in projects using Composer.

Support and Updates

WPGraphQL for Advanced Custom Fields will continue to get the same care and support I’ve provided since launch, but even better as I now have more time to focus on the WPGraphQL ecosystem. 

  • Github: If you run into issues or have ideas for feature requests, I kindly ask that you open issues on the Github repository.
  • Slack: If you have general questions, the WPGraphQL Slack workspace is a great place to seek support. If you’re not in the Slack workspace already, you can join here
  • Spectrum: WPGraphqL has an online community on Spectrum, which allows publicly visible and indexable async communication. You can visit the WPGraphQL Spectrum community here.

WPGraphQL and Gatsby

The Gatsby team and I are excited to invest more time into adding more features to WPGraphQL to benefit the entire headless WordPress & modern Javascript communities. 

Whether you’re using React or Vue, Next or Nuxt, Create React App or Gatsby, or anything else, we want WPGraphQL to be a great experience for all.

Of course, we believe in many cases there will be benefits of using WPGraphQL with Gatsby, and we’d love it if you gave Gatsby a try, but ultimately we want you to build great experience for your users using the tools you enjoy.

Thank you for your support and I’m looking forward to a bright future for GraphQL and WordPress.


Jason Bahl
Creator / Maintainer, WPGraphQL

WPGraphQL for FacetWP

I am pleased to announce the beta release of my FacetWP integration plugin for WPGraphQL. 

The main functionality was written quickly in late 2018 to fill a need to provide client-side access to FacetWP‚Äôs index and filtering functionality via WPGraphQL. As a proof-of-concept it worked exactly as needed. It was a lot less effort to create this plugin than it would have been to roll my own facet indexing module. 

Recently, I have had some down time between changing jobs and have been able to refactor and clean up the original code into something more usable by the larger WordPress and WPGraphQL community. If you have the need to expose the functionality of FacetWP via the GraphQL schema, I hope you find this plugin helpful!


To register WP Post Type(s) to be added to the schema, simply use the facet query registration function register_graphql_facet_type() as follows: 

// Register facet for Posts 
register_graphql_facet_type( 'post' ); // replace post with your CPT name as necessary 

Prerequisites: To use the plugin users must have already configured at least one facet in FacetWP and configured WPGraphQL.


The plugin uses reflection to expose all configured facets are available for querying. Each facet is added as an input argument to the query. 

Different facet types have unique inputs (eg a Slider has a min and max while Checkboxes is a simple array of strings). 

Given the post registration above the query variables might look something like this: 

const variables = { 
    after: '', // Use endCursor for paging 
    query: { 
        // example facet filtered on post ID 
        facet_name: [1, 2, 3], 
        // sample facet filtered on taxonomy term 
        term_facet_name: ['category-1', 'category-3'], 
    orderBy: { 
        field: 'DATE', 
        order: 'DESC', 


Registering a facet type will result in a new field on the Root Query. The field name is determined by the type to be queried. 

The payload of the new facet field includes: 

  • facets: The returned facet information
  • type connection: A WPGraphQL connection to the post type query 

Given the post registration earlier, the query and response payload might look like this: 

postFacet(where: {status: PUBLISH, query: $query}) { 
  facets { 
    choices { 
  posts(first: 10, after: $after, where: {search: $search, orderby: $orderBy}) { 
    pageInfo { 
    nodes { 


This payload includes all information relating to the queried facets and input variables. Available choices (including available count), settings and other relevant information are exposed in this field. 


This payload is a connection to the configured post type. It accepts all the pertinent GraphQL arguments (paging, sorting etc). 

This connection only returns posts that match the facet filter. 


This plugin provides users of WPGraphQL with access to an established and popular WordPress plugin for server-side filtering; FacetWP. I hope the WordPress community finds it helpful. It certainly was a great time saver for our project. 

Disclaimer and limitations: I have thoroughly tested Checkbox, fSelect and Radio facet types, as these are used in my app. There is provisional support for all other facet types, however these are not fully tested. As with any open source project, a detailed issue (or better yet a pull request) would be appreciated. 

Please see GitHub for further documentation and commentary.

WPGraphQL featured on

Today, I had the pleasure of being featured on the podcast with hosts Wes Bos and Scott Tolinsky.

In this episode we discussed how to use GraphQL with WordPress using the WPGraphQL plugin. I also announced that I’ve joined the Gatsby team to work on WPGraphQL an its immediate ecosystem full-tiime.

Below is the recording of the podcast.

WPGraphQL for ACF is here!

Many folks using WPGraphQL have asked about how to use GraphQL with their ACF data. The answer has typically been to manually map their ACF fields to the GraphQL schema using functions like register_graphql_field and register_graphql_object_type. For a few fields, this isn’t much of an issue, but when you have dozens of fields, this gets very tedious.

Today, we’ve released WPGraphQL for Advanced Custom Fields, which automatically adds your Advanced Custom Fields to your WPGraphQL Schema.

You can learn more about the plugin here:

Very excited to see what the community builds with this. If you have any questions, please contact us.

Upgrading to v0.3.0

WPGraphQL v0.3.0 is one of the most substantial releases to date for the plugin. You can read more about what was included in this release here and here.

Test in Staging Environment

It’s best practice to test plugin updates in staging environment, but I want to re-iterate that again here. Make sure you thoroughly test things when you update this plugin to v0.3.0, especially if you have any custom code that extends the Schema in any way.

Break: “roles” field on User type has changed shape

The User Type in the Schema previously had a roles field that returned a list of role names as strings.

Pre v0.3.0

  users {
    nodes {

Would return something like the following:

  "data": {
    "users": {
      "nodes": [
          "roles": [ 'administrator' ]


In v0.3.0, the roles field has changed to a Connection of roles. The query would change to something like the following:

  users {
    nodes {
      roles {
        nodes {

This change was made largely because Roles aren’t _really_ properties of a user. Roles are defined as entities on their own, and Users have a connection to one or more roles.

Break: Resolvers return models instead of WP_* instances

If you were extending some of the core Types in the Schema by adding fields, the first argument passed to the resolver used to be an instance of a core WP_* class. For instance, the Post Type would pass an instance of WP_Post down to field resolvers on that Type. Now, it will pass an instance of \WPGraphQL\Model\Post.

Here’s an example of a Field that may have been registered to the “old” version of the Schema:

register_graphql_field( 'Post', 'myNewField', [
  'type' => 'String',
  'resolve' => function( \WP_Post $post, $args, $context, $info ) {
    $data = get_post_meta( $post->ID, 'some_data', true );
    return $data ? data : null;  
] );

Here, we see the first argument passed down is a \WP_Post. In v0.3.0, that would be a \WPGraphQL\Model\Post like so:

register_graphql_field( 'Post', 'myNewField', [
  'type' => 'String',
  'resolve' => function( \WPGraphQL\Model\Post $post, $args, $context, $info ) {
    $data = get_post_meta( $post->ID, 'some_data', true );
    return $data ? data : null;   
] );

The following resolvers changed:

  • \WP_Post is now \WPGraphQL\Model\Post
  • \WP_User is now \WPGraphQL\Model\User
  • \WP_Comment is now \WPGraphQL\Model\Comment
  • \WP_Term is now \WPGraphQL\Model\Term

The full list of Models now available, that replaced what was there previously, is:

  • \WPGraphQL\Model\Avatar
  • \WPGraphQL\Model\Comment
  • \WPGraphQL\Model\CommentAuthor
  • \WPGraphQL\Model\Menu
  • \WPGraphQL\Model\MenuItem
  • \WPGraphQL\Model\Plugin
  • \WPGraphQL\Model\Post
  • \WPGraphQL\Model\PostType
  • \WPGraphQL\Model\Taxonomy
  • \WPGraphQL\Model\Term
  • \WPGraphQL\Model\Theme
  • \WPGraphQL\Model\User
  • \WPGraphQL\Model\UserRole

Depending on how you were extending the Schema, this may or may not have any affect on you.

Break: DataSource methods

The signature of DataSource methods have changed. If you were calling any DataSource methods in your extensions, you’ll likely need to refactor a bit. We recommend checking out the changes to that file so you understand all the changes for the methods you’re using, but here’s a quick example pointing out the difference:

Pre v0.3.0:

DataSource::resolve_post_object( $id, $post_type );


DataSource::resolve_post_object( $id, $context );

The specific way in which the signature for the DataSource method changed may be different depending on the method. If you’re calling any of these methods, check how it changed to be sure you’re using it the new way.

Break: Connection Resolver Classes

If you were making use of the ConnectionResolver classes in anyway, they’ve been completely revamped. They’ve been moved into the /Data/Connection directory, and are now stateful classes instead of classes with static methods. They are now much easier to digest and understand how to extend and create your own Connection Resolvers.

I won’t cover changes in detail here, but if you wrote any custom Connection Resolvers, and the new way of doing it doesn’t make sense after reading the new code, feel free to reach out and we can do our best to help you update.

Break: All kinds of restricted content is actually restricted now

With the introduction of the Model Layer, many fields and nodes that were previously accessible in public requests have now been restricted.

For example, our documentation previously mentioned that fields such as email on the User type was publicly exposed, and that if you wanted to hide it, you could do so via filter.

We’ve implemented a formal Model Layer that now handles restrictions like this out of the box, so fields that you may have been querying before, might not be returned anymore. Depending on your use case, this may be a break to you application, so it’s something to get familiar with.

How the Model Layer Works

We’ve written some docs on the Model Layer, but the general idea is that if you download install WordPress with nothing active but a standard `twenty-*` theme, the data that is exposed to a user should be the same data that is exposed to a GraphQL request.

For example, a non-authenticated user cannot access draft Posts in a vanilla WP install, so WPGraphQL will not return Draft posts to non authenticated users. (There’s more logic than that, but that’s just an example).

There are dozens of conditions in place that help determine whether fields should or should not be returned to the consumer making the request.

Other Breaking Changes

There might be some other breaking changes that we didn’t cover here. If you read this guide and also get familiar with the latest info on, but still run into issues that break your application after updating to v0.3.0, please reach out in Slack or Spectrum, or Open a Github Issue and we’ll do our best to help you get upgraded. We also highly recommend getting familiar with the source code of v0.3.0. We’ve commented the code very heavily to help provide an understanding of how everything is working and why it’s working that way.

If you find something you believe is a bug, as usual, please open an issue on Github

What’s coming in v0.3.0?

The next release of WPGraphQL will be version v0.3.0, and is slated to be released next week.

This release is arguably the most substantial release to date. It’s going to made up of 2 major features: “DataLoader” and “Model Layer


The role of DataLoader is to load data as efficiently as possible. You can read some of the highlights in the PR comment here:

Model Layer

The goal of the Model Layer is to centralize access control to objects and properties throughout the Graph. In short, that means we just want to make things more secure.

At the moment, some potentially sensitive data is exposed by default, and it’s the site owner’s responsibility to filter and adjust the Schema and resolvers to only expose data they want to be exposed in the API. You can read more about that here (under the Sensitive Data heading):

The Model Layer switches the plugins stance to be more restrictive by default, and allow site owners to loosen the restrictions when necessary, instead of expecting site owners to go through the effort of limiting potentially private content out of the box. Of course, each application is different, and our defaults may not be what you need for your application, so you will be able to filter access at a very granular level to make the GraphQL API work best for your specific needs.

The Model Layer centralizes access checks by taking into consideration the “current_user” making the request, then determines what objects (Posts, Terms, Comments, etc) and fields of those objects (Title, Content, etc) should be exposed to the user making the request. Fields like user emails will now only be exposed by default to authenticated users with “list_users” capabilities, for example. If you want to make override that new default and expose a field that we have restricted, you’ll have the ability to control that via various filters.

We’ll be working on a formal upgrade guide, as there will be numerous breaking changes for this release, but we think they’re all very welcome breaking changes.

You can keep an eye on progress in the branches here:

Security Audit

Over the past weekend we received the results of a Security Audit performed by Simone Quatrini of Pen Test Partners. The security audit pointed out some Insecure Access Control violations. Most of the violations in the report had already been resolved by the in-progress Model Layer branch, such as exposed user email addresses, which, as mentioned above is documented here.

There were 2 issues presented that we were not on our radar and we are grateful to Simone for bringing to our attention. We will be patching shortly as part of the v0.3.0 release. One issue, in particular, will be fixed for previous versions of the plugin as well, and details will be published about that once it has been resolved.

Full details of the Security Audit and resolutions to the issues will be published after the v0.3.0 release and other mentioned patches have been released.

WPGraphQL at WordCamp Montreal

√Čtienne B√©langer gave a talk at WordCamp Montreal 2018 titled: “Your First Headless WordPress Project with ReactJS and GraphQL”.

In the talk, he covers some basic differences between the WP REST API and WPGraphQL, then shows how to use React and Apollo Client to consume data from a WordPress site with the WPGraphQL plugin active.

Great talk, √Čtienne! ‚Äď and thanks for sharing the video with us.