Need help with wp-graphql-acf?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

wp-graphql
302 Stars 58 Forks 132 Commits 76 Opened issues

Description

WPGraphQL for Advanced Custom Fields

Services available

!
?

Need anything else?

Contributors list

WPGraphQL for Advanced Custom Fields

WPGraphQL for Advanced Custom Fields automatically exposes your ACF fields to the WPGraphQL Schema.

Install and Activate

WPGraphQL for Advanced Custom Fields is not currently available on the WordPress.org repository, so you must download it from Github, or Composer.

Installing From Github

To install the plugin from Github, you can download the latest release zip file, upload the Zip file to your WordPress install, and activate the plugin.

Click here to learn more about installing WordPress plugins from a Zip file.

Installing from Composer

composer require wp-graphql/wp-graphql-acf

Dependencies

In order to use WPGraphQL for Advanced Custom Fields, you must have WPGraphQL and Advanced Custom Fields (free or pro) installed and activated.

Adding Fields to the WPGraphQL Schema

TL;DR: Here's a video showing an overview of usage.

Advanced Custom Fields, or ACF for short, enables users to add Field Groups, either using a Graphical User Interface, PHP code, or local JSON to various screens in the WordPress dashboard, such as (but not limited to) the Edit Post, Edit User and Edit Term screens.

Whatever method you use to register ACF fields to your WordPress site should work with WPGraphQL for Advanced Custom Fields. For the sake of simplicity, the documentation below will primarily use the Graphic User Interface for examples.

Add ACF Fields to the WPGraphQL Schema

The first step in using Advanced Custom Fields with WPGraphQL is to create an ACF Field Group.

By default, field groups are not exposed to WPGraphQL. You must opt-in to expose your ACF Field Groups and fields to the WPGraphQL Schema as some information managed by your ACF fields may not be intended for exposure in a queryable API like WPGraphQL.

Show in GraphQL Setting

To have your ACF Field Group show in the WPGraphQL Schema, you need to configure the Field Group to "Show in GraphQL".

Using the ACF GUI

When using the ACF Graphic User Interface for creating fields, WPGraphQL for Advanced Custom Fields adds a Show in GraphQL field to Field Groups.

Setting the value of this field to "Yes" will show the field group in the WPGraphQL Schema, if a GraphQL Field Name is also set

Show in GraphQL Setting for ACF Field Groups

Registering Fields in PHP

When registering ACF Fields in PHP,

@todo

Supported Fields

In order to document interacting with the fields in GraphQL, an example field group has been created with one field of each type.

To replicate the same field group documented here you can download the exported field group and import it into your environment.

For the sake of documentation, this example field group has the location rule set to "Post Type is equal to Post", which will allow for the fields to be entered when creating and editing Posts in the WordPress dashboard, and will expose the fields to the

Post
type in the WPGraphQL Schema.

Location rule set to Post Type is equal to Post

Text Field

Text fields are added to the WPGraphQL Schema as a field with the Type

String
.

Text fields can be queried and a String will be returned.

Here, we have a Text field named

text
on the Post Edit screen within the "ACF Docs" Field Group.

Text field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      textArea
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "textArea": "Text Area Value"
       }
    }
  }
}

Text field Query

Text Area Field

Text Area fields are added to the WPGraphQL Schema as a field with the Type

String
.

Text Area fields can be queried and a String will be returned.

Here, we have a Text Area field named

text_area
on the Post Edit screen within the "ACF Docs" Field Group.

Text Area field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      textArea
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "textArea": "Text value"
       }
    }
  }
}

Text field Query

Number Field

Number fields are added to the WPGraphQL Schema as a field with the Type

Integer
.

Number fields can be queried and an Integer will be returned.

Here, we have a Number field named

number
on the Post Edit screen within the "ACF Docs" Field Group.

Number field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      number
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "number": 5
       }
    }
  }
}

Number field Query

Range Field

Range fields are added to the WPGraphQL Schema as a field with the Type

Integer
.

Range fields can be queried and an Integer will be returned.

Here, we have a Range field named

range
on the Post Edit screen within the "ACF Docs" Field Group.

Range field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      range
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "range": 5
       }
    }
  }
}

Range field Query

Email Field

Email fields are added to the WPGraphQL Schema as a field with the Type

String
.

Email fields can be queried and a String will be returned.

Here, we have an Email field named

email
on the Post Edit screen within the "ACF Docs" Field Group.

Email field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      email
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "email": "[email protected]"
       }
    }
  }
}

Email field Query

URL Field

Url fields are added to the WPGraphQL Schema as a field with the Type

String
.

Url fields can be queried and a String will be returned.

Here, we have a URL field named

url
on the Post Edit screen within the "ACF Docs" Field Group.

Url field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      url
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "url": "https://wpgraphql.com"
       }
    }
  }
}

URL field Query

Password Field

Password fields are added to the WPGraphQL Schema as a field with the Type

String
.

Password fields can be queried and a String will be returned.

Here, we have a Password field named

password
on the Post Edit screen within the "ACF Docs" Field Group.

Password field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      password
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
       "acfDocs": {
         "password": "123456"
       }
    }
  }
}

Password field Query

Image Field

Image fields are added to the WPGraphQL Schema as a field with the Type

MediaItem
.

Image fields can be queried and a MediaItem will be returned.

The

MediaItem
type is an Object type that has it's own fields that can be selected. So, instead of just getting the Image ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the
id
and
sourceUrl
.

Here, we have an Image field named

image
on the Post Edit screen within the "ACF Docs" Field Group.

Image field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    image {
      id
      sourceUrl(size: MEDIUM)
    }
  }
} 

And the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "image": {
          "id": "YXR0YWNobWVudDozMjM=",
          "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/03/babe-ruth-300x169.jpg"
        }
      }
    }
  }
}

Image field Query

File Field

File fields are added to the WPGraphQL Schema as a field with the Type

MediaItem
.

File fields can be queried and a MediaItem will be returned.

The

MediaItem
type is an Object type that has it's own fields that can be selected. So, instead of just getting the File ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the
id
and
mediaItemUrl
.

Here, we have a File field named

file
on the Post Edit screen within the "ACF Docs" Field Group.

File field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      file {
        id
        mediaItemUrl
      }
    }
  }
}

And the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "file": {
          "id": "YXR0YWNobWVudDozMjQ=",
          "mediaItemUrl": "http://acf2.local/wp-content/uploads/2020/03/little-ceasars-receipt-01282020.pdf"
        }
      }
    }
  }
}

File field Query

WYSIWYG Editor Field

WYSIWYG fields are added to the WPGraphQL Schema as a field with the Type

String
.

WYSIWYG fields can be queried and a String will be returned.

Here, we have a WYSIWYG field named

wysiwyg
on the Post Edit screen within the "ACF Docs" Field Group.

WYSIWYG field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post( id: "acf-example-test" idType: URI ) {
    acfDocs {
      wysiwyg
    }
  }
} 

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "wysiwyg": "

Some content in a WYSIWYG field

\n" } } } }

WYSIWYG field Query

oEmbed Field

oEmbed fields are added to the WPGraphQL Schema as a field with the Type

String
.

oEmbed fields can be queried and a String will be returned.

Here, we have a oEmbed field named

oembed
on the Post Edit screen within the "ACF Docs" Field Group.

oEmbed field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      oembed
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "oembed": "https://www.youtube.com/watch?v=ZEytXfaWwcc"
      }
    }
  }
}

oEmbed field Query

Gallery Field

Gallery fields are added to the WPGraphQL Schema as a field with the Type of

['list_of' => 'MediaItem']
.

Gallery fields can be queried and a list of MediaItem types will be returned.

Since the type is a list, we can expect an array to be returned. And since the Type within the list is

MediaItem
, we can ask for fields we want returned for each
MediaItem
in the list. In this case, let's say we want to ask for the
id
of each image and the
sourceUrl
, (size large).

Here, we have a Gallery field named

gallery
on the Post Edit screen within the "ACF Docs" Field Group.

Gallery field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      gallery {
        id
        sourceUrl(size: LARGE)
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "gallery": [
          {
            "id": "YXR0YWNobWVudDoyNTY=",
            "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth.jpg"
          },
          {
            "id": "YXR0YWNobWVudDoyNTU=",
            "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth-baseball-986x1024.jpg"
          }
        ]
      }
    }
  }
}

Gallery field Query

Select Field

Select fields (when configured to not allow mutliple selections) are added to the WPGraphQL Schema as a field with the Type

String
.

Select fields, without multiple selections allowed, can be queried and a String will be returned.

Here, we have a Select field named

select
on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected.

Select field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      select
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "select": "choice_1"
      }
    }
  }
}

Select field Query

Checkbox Field

Checkbox fields are added to the WPGraphQL Schema as a field with the Type

[ 'list_of' => 'String' ]
.

Checkbox fields can be queried and a list (array) of Strings (the selected values) will be returned.

Here, we have a Checkbox field named

checkbox
on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected.

Checkbox field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      checkbox
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "checkbox": [
          "choice_1"
        ]
      }
    }
  }
}

Checkbox field Query

Radio Button Field

Radio Button fields are added to the WPGraphQL Schema as a field with the Type

String
.

Radio Button fields can be queried and a String will be returned.

Here, we have a Radio Button field named

radio_button
on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected.

Radio Button field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      radioButton
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "radioButton": "choice_2"
      }
    }
  }
}

Radio Button field Query

Button Group Field

Button Group fields are added to the WPGraphQL Schema as a field with the Type

String
.

Button Group fields can be queried and a String will be returned.

Here, we have a Button Group field named

button_group
on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected.

Button Group field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      buttonGroup
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "buttonGroup": "choice_2"
      }
    }
  }
}

Radio Button field Query

True/False Field

True/False fields are added to the WPGraphQL Schema as a field with the Type

Boolean
.

True/False fields can be queried and a String will be returned.

Here, we have a True/False field named

true_false
on the Post Edit screen within the "ACF Docs" Field Group, and "true" is selected.

True/False field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      trueFalse
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "trueFalse": true
      }
    }
  }
}

True/False field Query

Link Field

Link fields are added to the WPGraphQL Schema as a field with the Type

ACF_Link
.

Link fields can be queried and a

ACF_Link
will be returned. The ACF Link is an object with fields that can be selected.

The available fields on the

ACF_Link
Type are:
  • target (String): The target of the link
  • title (String): The target of the link
  • url (String): The url of the link

Here, we have a Link field named

link
on the Post Edit screen within the "ACF Docs" Field Group.

Link field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      link {
        target
        title
        url
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "link": {
          "target": "",
          "title": "Hello world!",
          "url": "http://acf2.local/hello-world/"
        }
      }
    }
  }
}

Link field Query

Post Object Field

Post Object fields are added to the WPGraphQL Schema as a field with a Union of Possible Types the field is configured to allow.

If the field is configured to allow multiple selections, it will be added to the Schema as a List Of the Union Type.

Since Post Object fields can be configured to be limited to certain Post Types, the Union will represent those Types.

For example, if the Post Object field is configured to allow Posts of the

post
and
page
types to be selected:

Post Object field Post Type Config

Then the Union type for the field will allow

Post
and
Page
types to be returned, as seen in the Schema via GraphiQL:

Post Object field Union Possible Types

Here, we have a Post Object field named

post_object
on the Post Edit screen within the "ACF Docs" Field Group, configured with the Post "Hello World".

Post Object field in the Edit Post screen

As a GraphQL consumer, we don't know in advance if the value is going to be a Page or a Post.

So we can specify, via GraphQL fragment, what fields we want if the object is a Post, or if it is a Page.

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      postObject {
        __typename
        ... on Post {
          id
          title
          date
        }
        ... on Page {
          id
          title
        }
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "postObject": {
          "__typename": "Post",
          "id": "cG9zdDox",
          "title": "Hello world!",
          "date": "2020-02-20T23:12:21"
        }
      }
    }
  }
}

Post Object field Query

If the input of the field was saved as a Page, instead of a Post, like so:

Post Object field in the Edit Post screen

Then the same query above, would return the following results:

{
  "data": {
    "post": {
      "acfDocs": {
        "postObject": {
          "__typename": "Page",
          "id": "cGFnZToy",
          "title": "Sample Page"
        }
      }
    }
  }
}

Post Object field Query

Now, if the field were configured to allow multiple values, the field would be added to the Schema as a

listOf
, returning an Array of the Union.

If the field were set with a value of one Page, and one Post, like so:

Post Object field in the Edit Post screen

Then the results of the same query as above would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "postObject": [
          {
            "__typename": "Page",
            "id": "cGFnZToy",
            "title": "Sample Page"
          },
          {
            "__typename": "Post",
            "id": "cG9zdDox",
            "title": "Hello world!",
            "date": "2020-02-20T23:12:21"
          }
        ]
      }
    }
  }
}

Post Object field Query

Page Link Field

Page Link fields are added to the WPGraphQL Schema as a field with a Union of Possible Types the field is configured to allow.

Since Page Link fields can be configured to be limited to certain Post Types, the Union will represent those Types.

For example, if the Post Object field is configured to allow Posts of the

post
and
page
types to be selected:

Page Link field Post Type Config

Then the Union type for the field will allow

Post
and
Page
types to be returned, as seen in the Schema via GraphiQL:

Page Link field Union Possible Types

Here, we have a Page Link field named

page_link
on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to the "Sample Page" page.

Page Link field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      pageLink {
        __typename
        ... on Post {
          id
          title
          date
        }
        ... on Page {
          id
          title
        }
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "pageLink": {
          "__typename": "Page",
          "id": "cGFnZToy",
          "title": "Sample Page"
        }
      }
    }
  }
}

Page Link field Query

Here, we set the value to the "Hello World" Post:

Page Link field in the Edit Post screen

And the results of the same query are now:

{
  "data": {
    "post": {
      "acfDocs": {
        "pageLink": {
          "__typename": "Post",
          "id": "cG9zdDox",
          "title": "Hello world!",
          "date": "2020-02-20T23:12:21"
        }
      }
    }
  }
}

Page Link field Query

Relationship Field

Relationship fields are added to the WPGraphQL Schema as a field with a Union of Possible Types the field is configured to allow.

Since Relationship fields can be configured to be limited to certain Post Types, the Union will represent those Types.

For example, if the Post Object field is configured to allow Posts of the

post
and
page
types to be selected:

Relationship field Post Type Config

Then the Union type for the field will allow

Post
and
Page
types to be returned, as seen in the Schema via GraphiQL:

Relationship field Union Possible Types

Here, we have a Relationship field named

relationship
on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to "Hello World!" post, and the "Sample Page" page.

Relationship field in the Edit Post screen

This field can be Queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      relationship {
        __typename
        ... on Post {
          id
          title
          date
        }
        ... on Page {
          id
          title
        }
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "relationship": [
          {
            "__typename": "Post",
            "id": "cG9zdDox",
            "title": "Hello world!",
            "date": "2020-02-20T23:12:21"
          },
          {
            "__typename": "Page",
            "id": "cGFnZToy",
            "title": "Sample Page"
          }
        ]
      }
    }
  }
}

Relationship field Query

Taxonomy Field

The Taxonomy field is added to the GraphQL Schema as a List Of the Taxonomy Type.

For example, if the field is configured to the "Category" taxonomy, then the field in the Schema will be a List of the Category type.

Taxonomy field Taxonomy Config

Here, we have a Taxonomy field named

taxonomy
on the Post Edit screen within the "ACF Docs" Field Group, configured with the Category "Test Category".

Taxonomy field in the Edit Post screen

This field can be queried like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      taxonomy {
        __typename
        id
        name
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "taxonomy": [
          {
            "__typename": "Category",
            "id": "Y2F0ZWdvcnk6Mg==",
            "name": "Test Category"
          }
        ]
      }
    }
  }
}

Taxonomy field Query

User Field

User fields are added to the WPGraphQL Schema as a field with a User type.

Here, we have a User field named

user
on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" as the value.

User field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      user {
        id
        username
        firstName
        lastName
      }
    }
  }
}

and the response would look like:

{
  "data": {
    "post": {
      "acfDocs": {
        "user": {
          "id": "dXNlcjox",
          "username": "jasonbahl",
          "firstName": "Jason",
          "lastName": "Bahl"
        }
      }
    }
  }
}

User field Query with one selection

If the field is configured to allow multiple selections, it's added to the Schema as a List Of the User type.

Here, we have a User field named

user
on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" as the value.

User field in the Edit Post screen

and the response to the same query would look like:

{
  "data": {
    "post": {
      "acfDocs": {
        "user": [
          {
            "id": "dXNlcjox",
            "username": "jasonbahl",
            "firstName": "Jason",
            "lastName": "Bahl"
          },
          {
            "id": "dXNlcjoy",
            "username": "WPGraphQL",
            "firstName": "WP",
            "lastName": "GraphQL"
          }
        ]
      }
    }
  }
}

User field Query with multiple selections

Google Map Field

Google Map fields are added the WPGraphQL Schema as the

ACF_GoogleMap
Type.

The

ACF_GoogleMap
Type has fields that expose location data. The available fields are:
  • city (String): The city associated with the location
  • country (String): The country associated with the location
  • countryShort (String): The country abbreviation associated with the location
  • latitude (String): The latitude associated with the location
  • longitude (String): The longitude associated with the location
  • placeId (String): Place IDs uniquely identify a place in the Google Places database and on Google Maps.
  • postCode (String): The post code associated with the location
  • state (String): The state associated with the location
  • stateShort (String): The state abbreviation associated with the location
  • streetAddress (String): The street address associated with the location
  • streetName (String): The street name associated with the location
  • streetNumber (String): The street number associated with the location
  • zoom (String): The zoom defined with the location

Here, we have a Google Map field named

google_map
on the Post Edit screen within the "ACF Docs" Field Group, set with the Address "1 Infinite Loop, Cupertino, CA 95014, USA" as the value.

Google Map field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      googleMap {
        streetAddress
        streetNumber
        streetName
        city
        state
        postCode
        countryShort
      }
    }
  }
}

and the response would look like:

{
  "data": {
    "post": {
      "acfDocs": {
        "googleMap": {
          "streetAddress": "1 Infinite Loop, Cupertino, CA 95014, USA",
          "streetNumber": "1",
          "streetName": "Infinite Loop",
          "city": "Cupertino",
          "state": "California",
          "postCode": "95014",
          "placeId": "ChIJHTRqF7e1j4ARzZ_Fv8VA4Eo",
          "countryShort": "US"
        }
      }
    }
  }
}

Google Map field in the Edit Post screen

Date Picker Field

The Date Picker field is added to the WPGraphQL Schema as field with the Type

String
.

Date Picker fields can be queried and a String will be returned.

Here, we have a Date Picker field named

date_picker
on the Post Edit screen within the "ACF Docs" Field Group, and "13/03/2020" is the date set.

Date Picker field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      datePicker
    }
  }
}

and the result of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "datePicker": "13/03/2020"
      }
    }
  }
}

Date Picker field in the Edit Post screen

Date/Time Picker Field

The Date/Time Picker field is added to the WPGraphQL Schema as field with the Type

String
.

Date/Time Picker fields can be queried and a String will be returned.

Here, we have a Date/Time Picker field named

date_time_picker
on the Post Edit screen within the "ACF Docs" Field Group, and "20/03/2020 8:15 am" is the value.

Date Picker field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      dateTimePicker
    }
  }
}

and the result of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "dateTimePicker": "20/03/2020 8:15 am"
      }
    }
  }
}

Date/Time Picker field in the Edit Post screen

Time Picker Field

The Time Picker field is added to the WPGraphQL Schema as field with the Type

String
.

Time Picker fields can be queried and a String will be returned.

Here, we have a Time Picker field named

time_picker
on the Post Edit screen within the "ACF Docs" Field Group, and "12:30 am" is the value.

Time Picker field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      timePicker
    }
  }
}

and the result of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "timePicker": "12:30 am"
      }
    }
  }
}

Time Picker field in the Edit Post screen

Color Picker Field

The Color Picker field is added to the WPGraphQL Schema as field with the Type

String
.

Color Picker fields can be queried and a String will be returned.

Here, we have a Color Picker field named

color_picker
on the Post Edit screen within the "ACF Docs" Field Group, and "#dd3333" is the value.

Color Picker field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      colorPicker
    }
  }
}

and the result of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "colorPicker": "12:30 am"
      }
    }
  }
}

Color Picker field in the Edit Post screen

Message Field

Message fields are not currently supported.

Accordion Field

Accordion Fields are not currently supported.

Tab Field

Tab fields are not currently supported.

Group Field

Group Fields are added to the WPGraphQL Schema as fields resolving to an Object Type named after the Group.

Here, we have a Group field named

group
on the Post Edit screen within the "ACF Docs" Field Group. Within the "group" field, we have a Text Field named
text_field_in_group
and a Text Area field named
text_area_field_in_group

Group field in the Edit Post screen

We can query the fields within the group like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      group {
        textFieldInGroup
        textAreaFieldInGroup
      }
    }
  }
}

And the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "group": {
          "textFieldInGroup": "Text value, in group",
          "textAreaFieldInGroup": "Text are value, in group"
        }
      }
    }
  }
}

Group field Query

Repeater Field

Repeater Fields are added to the Schema as a List Of the Type of group that makes up the fields.

For example, we've created a Repeater Field that has a Text Field named

text_field_in_repeater
and an Image Field named
image_field_in_repeater
.

Here, the Repeater Field is populated with 2 rows: - Row 1: - Text Field: Text Value 1 - Image: 256 - Row 2: - Text Field: Text Value 2 - Image: 255

Repeater field in the Edit Post screen

This field can be queried in GraphQL like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      repeater {
        textFieldInRepeater
        imageFieldInRepeater {
          databaseId
          id
          sourceUrl
        }
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "repeater": [
          {
            "textFieldInRepeater": "Text Value 1",
            "imageFieldInRepeater": {
              "id": "YXR0YWNobWVudDoyNTY=",
              "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth.jpg"
            }
          },
          {
            "textFieldInRepeater": "Text Value 2",
            "imageFieldInRepeater": {
              "id": "YXR0YWNobWVudDoyNTU=",
              "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-scaled.jpg"
            }
          }
        ]
      }
    }
  }
}

Repeater field Query

Flexible Content Field

The Flexible Content is a powerful ACF field that allows for groups of fields to be organized into "Layouts".

These Layouts can be made up of other types of fields, and can be added and arranged in any order.

Flexible Content Fields are added to the WPGraphQL Schema as a List Of Unions.

The Union for a Flex Field is made up of each Layout in the Flex Field as the possible Types.

In our example, we've created a Flex Field with 3 layouts named "Layout 1", "Layout 2" and "Layout 3". In the Schema, we can see the Flex Field Union's Possible Types are these 3 layouts.

Flex Fields Schema Union Possible Types

Each of these Layout types will contain the fields defined for the layout and can be queried like fields in any other Group.

Here's an example of a Flex Field named

flexible_content
, with 3 layouts:
  • Layout 1
    • Text field named "text"
    • Text field named "anothertextfield"
  • Layout 2
    • Image field named "image"
  • Layout 3
    • Gallery field named "gallery"

Above are the possible layouts and their fields. These layouts can be added and arranged in any order. While we, as a GraphQL consumer, don't know ahead of time what order they will be in, we do know what the possibilities are.

Here's an example of a Flex Field named

flexible_content
with the values saved as "Layout One", "Layout Two" and "Layout Three", in that order, all populated with their respective fields.

Flex field in the Edit Post screen

We can query this field like so:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      flexibleContent {
        __typename
        ... on Post_Acfdocs_FlexibleContent_LayoutOne {
          text
          anotherTextField
        }
        ... on Post_Acfdocs_FlexibleContent_LayoutTwo {
          image {
            id
            sourceUrl(size: MEDIUM)
          }
        }
        ... on Post_Acfdocs_FlexibleContent_LayoutThree {
          gallery {
            id
            sourceUrl(size: MEDIUM)
          }
        }
      }
    }
  }
}

and the results of the query would be:

{
  "data": {
    "post": {
      "acfDocs": {
        "flexibleContent": [
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne",
            "text": "Text Value One",
            "anotherTextField": "Another Text Value"
          },
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo",
            "image": {
              "id": "YXR0YWNobWVudDoyNTY=",
              "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg"
            }
          },
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree",
            "gallery": [
              {
                "id": "YXR0YWNobWVudDoyNTY=",
                "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg"
              },
              {
                "id": "YXR0YWNobWVudDoyNTU=",
                "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg"
              }
            ]
          }
        ]
      }
    }
  }
}

Flex field Query

If we were to re-arrange the layouts, so that the order was "Layout Three", "Layout One", "Layout Two", the results of the query would be:

"data": {
    "post": {
      "acfDocs": {
        "flexibleContent": [
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree",
            "gallery": [
              {
                "id": "YXR0YWNobWVudDoyNTY=",
                "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg"
              },
              {
                "id": "YXR0YWNobWVudDoyNTU=",
                "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg"
              }
            ]
          }
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne",
            "text": "Text Value One",
            "anotherTextField": "Another Text Value"
          },
          {
            "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo",
            "image": {
              "id": "YXR0YWNobWVudDoyNTY=",
              "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg"
            }
          },
        ]
      }
    }
  }

Flex field Query 2

Clone Field

The clone field is not fully supported (yet). We plan to support it in the future.

Options Pages

Reference: https://www.advancedcustomfields.com/add-ons/options-page/

To add an option page and expose it to the graphql schema, simply add 'showingraphql' => true when you register an option page.

Example Usage

function register_acf_options_pages() {

// check function exists
if ( ! function_exists( 'acf_add_options_page' ) ) {
    return;
}

// register options page
$my_options_page = acf_add_options_page(
    array(
        'page_title'      => __( 'My Options Page' ),
        'menu_title'      => __( 'My Options Page' ),
        'menu_slug'       => 'my-options-page',
        'capability'      => 'edit_posts',
        'show_in_graphql' => true,
    )
);

}

add_action( 'acf/init', 'register_acf_options_pages' ) Example Query query GetMyOptionsPage { myOptionsPage { someCustomField } }

Alternatively, it's you can check the Fields API Reference to learn about exposing your custom fields to the Schema.

Location Rules

Advanced Custom Fields field groups are added to the WordPress dashboard by being assinged "Location Rules".

WPGraphQL for Advanced Custom Fields uses the Location Rules to determine where in the GraphQL Schema the field groups/fields should be added to the Schema.

For example, if a Field Group were assigned to "Post Type is equal to Post", then the field group would show in the WPGraphQL Schema on the

Post
type, allowing you to query for ACF fields of the Post, anywhere you can interact with the
Post
type in the Schema.

Supported Locations

@todo: Document supported location rules and how they map from ACF to the WPGraphQL Schema

Why aren't all location rules supported?

You might notice that some location rules don't add fields to the Schema. This is because some location rules are based on context that doesn't exist when the GraphQL Schema is generated.

For example, if you have a location rule to show a field group only on a specific page, how would that be exposed the the Schema? There's no Type in the Schema for just one specific page.

If you're not seeing a field group in the Schema, look at the location rules, and think about how the field group would be added to a Schema that isn't aware of context like which admin page you're on, what category a Post is assigned to, etc.

If you have ideas on how these specific contextual rules should be handled in WPGraphQL, submit an issue so we can consider how to best support it!

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.