graphql.md

GraphQL

As of version 2.5.0, Neo supports GraphQL that's now a feature within Craft CMS.

Fragment syntax

{neo field handle}_{neo block type handle}_BlockType

How to use

In the following example we'll be using a Neo field with the handle body.

Single level queries

Example on how to query the text block type that has a text field within:

body {
    ... on body_text_BlockType {
        # text field
        text
    } 
}

Returned Data example:

"body": [
    {
        "text": "Test content"
    }
]

---

Another example with assets:

body {
    ... on body_media_BlockType {
        # asset field
        media {
            url
        }
    } 
}

Returned Data example:

"body": [
    {
        "media": [
            {
                "url": "assets/media/image.png"
            }
        ]
    }
]

---

Multi level queries

Multi level block types will have a field called children. These will return the children blocks within the parent block type.

Example:

body {
    ... on body_text_BlockType {
        text
    }
    ... on body_myContent_BlockType {
        children {
            ... on body_text_BlockType {
                # text field
                text
            }

            ... on body_media_BlockType {
                # asset field
                media {
                    url
                }
            }
        }
    }
}

Returned data example:

"body": [
    {
        "text": test
    },
    {
        "children": [
            {
              "text": "test"
            },
            {
                "media": [
                    {
                      "url": "assets/media/image1.png"
                    }
                ]
            }
        ]
    }
]

---

Multiple levels example:

body {
    ... on body_myContent_BlockType {
        children {
            ... on body_text_BlockType {
                # text field
                text
            }

            ... on body_innerContent_BlockType {
                children: {
                    text
                }
            }

            ... on body_media_BlockType {
                # asset field
                media {
                    url
                }
            }
        }
    }
}

Returned data example:

"body": [
    {
        "children": [
            {
              "text": "test"
            },
            {
                "children": [
                    {
                      "text": "test test"
                    },
                    {
                      "text": "test test test"
                    }
                ]
            },
            {
                "media": [
                    {
                      "url": "assets/media/image1.png"
                    }
                ]
            }
        ]
    }
]

Returning all blocks

By default, a Neo field query will return only the blocks at the top level of the field. Other levels can be targeted using the level argument, and setting level to 0 will return all blocks. Blocks' levels can be returned using the level field.

Returning all blocks example:

body(level: 0) {
    ... on body_text_BlockType {
        level
        text
    }
}

Returned data example:

"body": [
    {
        "level": 1,
        "text": "Parent text block"
    },
    {
        "level": 2,
        "text": "Child text block"
    },
    {
        "level": 1,
        "text": "Another top-level text block"
    }
]

---

Mutations

Mutating Neo fields is largely the same process as with Matrix fields, but with two differences:

• Neo-related input types have Neo in their name, rather than Matrix; e.g. the input type for a Neo field with the handle yourNeoField is yourNeoField_NeoInput.
• Neo block data can include a level argument for setting the block's level. If level isn't specified for new blocks, it will default to 1.