GraphQL Fragments: Nested, Reusable, and Powerful

GraphQL lets you ask for exactly the data you need—but when your queries get long or repetitive, things can quickly get messy. That’s where GraphQL fragments come in.

Fragments help you:

• Reuse sets of fields across multiple queries

• Simplify large queries with nested objects

• Avoid repeating the same structure
  
  

This guide breaks down how GraphQL fragments work, why they matter, and how to use them effectively in real-world projects.

---

What Is a GraphQL Fragment?

A GraphQL fragment is a reusable unit of a selection set. That means instead of rewriting the same group of fields over and over, you define them once and include them wherever needed.

Example Without Fragment

query {
  blogPost {
    title
    author {
      name
      bio
    }
  }
  article {
    headline
    author {
      name
      bio
    }
  }
}

Notice how the author fields are repeated.

With a Fragment

fragment AuthorDetails on Author {
  name
  bio
}

query {
  blogPost {
    title
    author {
      ...AuthorDetails
    }
  }
  article {
    headline
    author {
      ...AuthorDetails
    }
  }
}

Cleaner and more reusable.

---

How Fragments Work

A fragment must:

1. Be declared at the bottom of your query.

2. Match the type you're querying.

3. Use ...FragmentName inside your query.
   
   

Anatomy:

fragment FragmentName on TypeName {
  field1
  field2
}

Use it with:

...FragmentName

---

Why Use GraphQL Fragments?

• Cleaner code: Makes your queries easier to read and maintain

• DRY principle: Don’t Repeat Yourself

• Reusable patterns: Useful when querying similar types like Page, Post, Product
  
  

Works with nested content: Especially in Agility CMS where components are nested deeply.

---

Example with Agility CMS Content

Let’s say you have a content model with multiple content types that share a common reference field: linkedAuthor.

Fragment Declaration

fragment AuthorInfo on Author {
  name
  title
  socialLinks
}

Use in Query

fragment AuthorInfo on Author {
  name
  title
  socialLinks
}

query {
  post(id: "123") {
    title
    linkedAuthor {
      ...AuthorInfo
    }
  }
  podcast(id: "456") {
    name
    linkedAuthor {
      ...AuthorInfo
    }
  }
}

---

Fragments in Nested Structures

Fragments really shine in nested content blocks or structured content.

Example

fragment ImageFields on Image {
  url
  altText
  width
  height
}

query {
  heroBanner {
    heading
    image {
      ...ImageFields
    }
  }
  testimonialSection {
    quote
    avatar {
      ...ImageFields
    }
  }
}

---

Can You Nest Fragments?

Yes! You can use fragments within other fragments.

Example

fragment AuthorFields on Author {
  name
  bio
}

fragment PostFields on Post {
  title
  date
  author {
    ...AuthorFields
  }
}

query {
  allPosts {
    ...PostFields
  }
}

This is perfect when working with modular content types in Agility CMS, where references and nested structures are common.

---

Fragment Gotchas

• Fragments must match the type exactly (check the schema!)

• Don’t overuse: Small, specific fragments are better than one giant one

• Playground requires fragments at the bottom
  

• Use the Docs panel in GraphQL Playground to confirm the field types

---

Use Cases for Fragments

• Querying multiple content types with shared structures (e.g. Page, Post, Product)

• Creating reusable UI components in your frontend that always need the same fields

• Making your queries readable and maintainable

• Building with Next.js + Agility CMS, where GraphQL queries are used in page-level data fetching

---

Summary

GraphQL fragments are a key feature for writing clean, scalable queries. They let you define once, reuse often—which is critical when building with a headless CMS like Agility CMS.

Next Steps:

• Explore your schema in the Agility CMS GraphQL Playground

• Use fragments in Next.js projects to simplify your code

• Learn how fragments relate to structured content modeling

Try fragments in your next GraphQL query and see how much cleaner your API requests become.