Skip to main content

Using GraphQL Fragments

Fragments allow you to reuse parts of GraphQL queries. It also allows you to split up complex queries into smaller, easier to understand components.

The building blocks of a fragment

Here is an example fragment:

A fragment consists of three components:

  1. FragmentName: the name of the fragment that will be referenced later.
  2. TypeName: the GraphQL type of the object the fragment will be used on. This is important because you can only query for fields that actually exist on a given object.
  3. The body of the query. You can define any fields with any level of nesting in here, the same that you would elsewhere in a GraphQL query

Creating and using a fragment

A fragment can be created inside any GraphQL query, but it’s good practice to create the query separately. More organization advice in the Conceptual Guide.

This defines a fragment named SiteInformation. Now it can be used from within the page’s GraphQL query:

When compiling your site, Gatsby preprocesses all GraphQL queries it finds. Therefore, any file that gets included in your project can define a snippet. However, only Pages can define GraphQL queries that actually return data. This is why you can define the fragment in the component file - it doesn’t actually return any data directly.

Further reading

Edit this page on GitHub