GraphQL Fragments

Fragments are reusable pieces of a query. When multiple queries need the same set of fields from the same type, you define those fields once in a fragment and reuse it everywhere. This keeps your queries clean and avoids copy-pasting field lists.

The Copy-Paste Problem Fragments Solve

Imagine a social app where three different queries all need the same user card fields: name, avatar, and username. Without fragments, you write those three fields in every query. When the UserCard design changes and needs a new field, you update three places instead of one.

  Without fragments — repeated field lists:
  ──────────────────────────────────────────
  query Feed {
    posts {
      author {
        name        ← repeated
        avatar      ← repeated
        username    ← repeated
      }
    }
  }

  query Search {
    results {
      author {
        name        ← repeated
        avatar      ← repeated
        username    ← repeated
      }
    }
  }

Defining a Fragment

A fragment starts with the fragment keyword, a name you choose, the keyword on, and the type it applies to. The curly braces hold the fields.

  fragment UserCard on User {
    name
    avatar
    username
  }

Using a Fragment with the Spread Operator

Spread a fragment into a query using three dots ... followed by the fragment name. GraphQL replaces that spread with the full field list at execution time.

  Fragment definition:          Used in two queries:
  ────────────────────          ────────────────────
  fragment UserCard on User {   query Feed {
    name                          posts {
    avatar                          author {
    username                          ...UserCard
  }                               }
                                  }
                                }

                                query Search {
                                  results {
                                    author {
                                      ...UserCard
                                    }
                                  }
                                }

Fragment Expands at Runtime

When GraphQL processes a query, it expands every fragment spread into its fields. The server sees the full field list as if you had written every field manually.

  What you write:               What GraphQL executes:
  ───────────────               ──────────────────────
  author {                      author {
    ...UserCard                   name
  }                               avatar
                                  username
                                }

Fragments and Aliases Together

Use fragments alongside aliases when you need the same type's fields in multiple positions with different response keys.

  fragment ProductInfo on Product {
    name
    price
  }

  {
    cheap:    product(id: "1") { ...ProductInfo }
    premium:  product(id: "2") { ...ProductInfo }
  }

  Response:
  ─────────
  {
    "cheap":   { "name": "Basic Pen",   "price": 1.50 },
    "premium": { "name": "Luxury Pen",  "price": 45.00 }
  }

Inline Fragments for Conditional Fields

Inline fragments let you select fields from a specific type within a union or interface result. You do not define them separately — they appear directly inside the query. This comes up most often when a field can return different types.

  Schema:
  ────────
  union SearchResult = Book | Movie

  type Query {
    search(term: String!): [SearchResult]
  }

  Query with inline fragments:
  ─────────────────────────────
  {
    search(term: "space") {
      ... on Book {        ← Only if result is a Book
        title
        author
      }
      ... on Movie {       ← Only if result is a Movie
        title
        director
        runtime
      }
    }
  }

Key Points

• Fragments define a named, reusable set of fields for a specific type.
• Spread a fragment with ...FragmentName wherever you need those fields.
• Fragments prevent repetition and make updates easier — change the fragment once, it updates everywhere.
• Inline fragments (... on TypeName) select conditional fields from union or interface types.