Fragment vs Inline Fragment in GraphQL: Key Differences and Usage

In GraphQL, a fragment is a reusable unit of fields defined separately and included by name, while an inline fragment is defined directly inside a query for conditional fields, often used with interfaces or unions. Fragments promote reuse, whereas inline fragments handle type-specific selections within a single query.

Quick Comparison

This table summarizes the main differences between fragment and inline fragment in GraphQL.

Aspect	Fragment	Inline Fragment
Definition	Named reusable set of fields	Anonymous conditional fields inside a query
Syntax	Defined separately with fragment keyword	Defined inline with ... on Type syntax
Reusability	Can be reused across multiple queries	Cannot be reused, specific to one query
Use Case	Avoids repetition of common fields	Handles type-specific fields in unions/interfaces
Placement	Outside main query, then spread inside	Directly inside query or mutation
Supports Type Conditions	Yes, with on Type	Yes, mandatory for conditional selection

Key Differences

A fragment in GraphQL is a named block of fields that you define once and then include in multiple queries or mutations by referencing its name. This helps reduce repetition and keeps queries clean and maintainable. Fragments are defined outside the main query body and can be reused wherever needed.

On the other hand, an inline fragment is written directly inside a query or mutation. It is anonymous and used mainly for conditional field selection based on the runtime type of the object, especially when querying interfaces or union types. Inline fragments allow you to specify fields that only apply if the object matches a certain type.

While both fragments and inline fragments support type conditions using the on Type syntax, the key difference is that fragments are reusable and named, whereas inline fragments are one-off and embedded directly in the query. This makes fragments ideal for shared field sets, and inline fragments ideal for handling polymorphic data structures.

Code Comparison

Here is an example showing a named fragment used to fetch common fields for a Character type in a Star Wars API query.

graphql

fragment CharacterDetails on Character {
  name
  species
  homePlanet
}

query GetHero {
  hero {
    ...CharacterDetails
  }
  human(id: "1000") {
    ...CharacterDetails
  }
}

Output

{
  "data": {
    "hero": {
      "name": "Luke Skywalker",
      "species": "Human",
      "homePlanet": "Tatooine"
    },
    "human": {
      "name": "Han Solo",
      "species": "Human",
      "homePlanet": "Corellia"
    }
  }
}

Inline Fragment Equivalent

The same data can be fetched using inline fragments inside the query, specifying type conditions directly where needed.

graphql

query GetHero {
  hero {
    ... on Character {
      name
      species
      homePlanet
    }
  }
  human(id: "1000") {
    ... on Character {
      name
      species
      homePlanet
    }
  }
}

Output

{
  "data": {
    "hero": {
      "name": "Luke Skywalker",
      "species": "Human",
      "homePlanet": "Tatooine"
    },
    "human": {
      "name": "Han Solo",
      "species": "Human",
      "homePlanet": "Corellia"
    }
  }
}

When to Use Which

Choose fragment when you have a set of fields repeated in multiple places or queries, and you want to keep your queries DRY (Don't Repeat Yourself). Fragments improve readability and maintainability by centralizing common field selections.

Choose inline fragment when you need to select fields conditionally based on the runtime type of an object, especially when working with interfaces or union types. Inline fragments are perfect for one-off type-specific selections within a single query.

Key Takeaways

Fragments are named, reusable field sets defined outside queries for sharing common fields.

Inline fragments are anonymous, used inside queries for conditional type-based field selection.

Use fragments to avoid repetition and improve query maintainability.

Use inline fragments to handle polymorphic types like interfaces and unions.

Both support type conditions but serve different purposes in query design.