GraphQL Formatter

Why format GraphQL

GraphQL queries are often built in code, logged on one line, or copied from network traces in the browser. A query with a few levels of nesting is almost impossible to read in that form. You cannot tell which fields belong to which object, or where one fragment ends.

A GraphQL formatter puts each field on its own line and indents every selection set one level deeper than its parent. The structure of the query then matches the structure of the response you get back, which makes it easy to check.

This tool uses Prettier 3 with its GraphQL plugin, in your browser.

How to use it

1. Paste a query, mutation or schema into the left box. It is formatted right after you paste.
2. Or press Open file to load a .graphql file, or Sample for an example.
3. Choose the Indent: 2 spaces, 4 spaces or Tabs.
4. Choose the Line width. Arguments and variable lists that do not fit are split over several lines.
5. Press Format or Ctrl+Enter.
6. Press Copy, or Download to save a .graphql file.

Once you have formatted once, the output follows your typing. If there is a syntax error, the message gives its line and column, and Show in input jumps to it.

Before and after

A query on one line:

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

After Format with 2 spaces:

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

Variables get a space after the colon, the default value 5 gets spaces around =, and every nested selection set is indented. You can now see that title is a field of node, inside edges, inside posts.

Mutations and input objects

Input objects that fit within the line width stay on one line:

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

When it does not fit, the arguments are split. Here is the same mutation with a line width of 40:

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

Note that commas between input fields are dropped on multi-line objects. In GraphQL, commas are optional and count as whitespace.

Fragments

Fragments and spreads are kept in the order you wrote them:

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

Schema files

Schema definition language is formatted with the same rules. One field per line, and enum values each on their own line:

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

With Indent set to 4 spaces, query{viewer{login}} becomes:

query {
    viewer {
        login
    }
}

Syntax errors

The GraphQL parser is strict, and its messages are short. Two common ones:

• A missing closing brace at the end gives Line 4, column 1: Syntax Error: Expected Name, found <EOF>. The parser reached the end of the input while it was still inside a selection set.
• An argument with no value, as in user(id: ), gives Line 2, column 12: Syntax Error: Unexpected ")".

Count your braces from the position shown. A formatter is also a quick way to find a missing brace in a long query: paste it, and if the error points at the end of the input, a selection set was never closed.

Limits

• Only syntax is checked. Field names, argument types and required variables are not validated against any schema.
• The formatter does not reorder fields, sort types or remove unused fragments.
• For queries inside gql template strings in JavaScript or TypeScript, paste only the query text here, then put the result back. The JavaScript formatter and TypeScript formatter format the surrounding code but leave the template string as it is.
• Variables are sent as JSON, not GraphQL. Format a variables object in the JSON formatter.

Other ways to format GraphQL

• VS Code: with the Prettier extension, Format Document (Shift+Alt+F on Windows, Shift+Option+F on macOS) formats .graphql and .gql files with the same rules as this page.
• Command line: npx prettier --write schema.graphql.
• GraphQL IDEs such as GraphiQL have a Prettify button that formats the query in the editor. It is handy while you are testing, and this page is useful when you only have the text and no IDE at hand.