How to Use GraphQL Fragments

Fragments are a clever and elegant way of avoiding code duplication in your API calls by creating reusable chunks of code.

What are fragments?

In GraphQL, fragments allow us to create sets of fields that we can include in different places within our queries. Fragments help us to avoid code duplication in our GraphQL operations.

In short, fragments are reusable units of code that improve the clarity and readability of our queries or mutations.

Using fragments to avoid coding duplication 

Let's use the same example we have used in our guide about aliases to exemplify a good use case for fragments:

query {
  orderOne: orderById(id: "c6cdba3f-1220-44c3-aadc-eeec0f9eb1aa") {
    total
  }
  
  orderTwo: orderById(id: "20de7a12-9f2d-4e84-9f1c-21003b00ea63") {
    total
  }
}

In the query above, we're retrieving data about two different orders in a single API call—and we're using aliases to rename the fields orderById and avoid naming conflicts. For both orders, we're asking for only one field: total.

Now imagine that our app or integration needs to retrieve not just the total field but also the following fields:

• subtotal
• taxPercentage
• taxProvider
• taxTotal
• paymentStatus
• shippingStatus
• updatedAt

Our updated query, then, will look like this:

query {
  orderOne: orderById(id: "5696db94-66ee-46a5-b862-168235c4b5ab") {
    total
    subTotal
    taxPercentage
    taxProvider
    taxTotal
    paymentStatus
    shippingStatus
    updatedAt
  }
  
  orderTwo: orderById(id: "66c4a31e-39a4-48b1-af00-5f14fd7a37d1") {
    total
    subTotal
    taxPercentage
    taxProvider
    taxTotal
    paymentStatus
    shippingStatus
    updatedAt
  }
}

We now have many repeated fields in our query. Would it not be nice to write the repeated fields only once and then reuse them?

That's where fragments can help.

Here's the syntax to write fragments in GraphQL:

fragment orderDetails on Order {
    total
    subTotal
    taxPercentage
    taxProvider
    taxTotal
    paymentStatus
    shippingStatus
    updatedAt
} 

• fragment

  The keyword "fragment" indicates that we're writing a fragment.

• orderDetails

  orderDetails is the name we're giving to our fragment. 

• on Order {

  The keyword "on" is important. It indicates from which object in the schema our fields must come from. In this case, all fields must come from the Order object, the returned object from the orderById query.

•     total
      subTotal
      taxPercentage
      taxProvider
      taxTotal
      paymentStatus
      shippingStatus
      updatedAt
  } 

  Then we have the fields we want to retrieve from the Order object.

Now that we have created our fragment, we can use it in our query:

query {
  orderOne: orderById(id: "5696db94-66ee-46a5-b862-168235c4b5ab") {
    ...orderDetails
  }
  
  orderTwo: orderById(id: "66c4a31e-39a4-48b1-af00-5f14fd7a37d1") {
    ...orderDetails
  }
}

fragment orderDetails on Order {
    total
    subTotal
    taxPercentage
    taxProvider
    taxTotal
    paymentStatus
    shippingStatus
    updatedAt
} 

To use a created fragment, type three dots, and the fragment's name. Here's a response sample to our query:

{
  "data": {
    "orderOne": {
      "total": 70.79,
      "subTotal": 58.99,
      "taxPercentage": 20,
      "taxProvider": "BRIKL_TAX_SETTINGS",
      "taxTotal": 11.8,
      "paymentStatus": "PAID",
      "shippingStatus": "PENDING",
      "updatedAt": "2022-08-23T08:01:46.733"
    },
    "orderTwo": {
      "total": 68.8,
      "subTotal": 49,
      "taxPercentage": 20,
      "taxProvider": "AVALARA",
      "taxTotal": 9.8,
      "paymentStatus": "PAID",
      "shippingStatus": "SHIPPED",
      "updatedAt": "2022-08-29T03:10:52.274"
    }
  }
}