How to Use Fragment on Interface in GraphQL

In GraphQL, you can use fragments on an interface to select common fields shared by all types implementing that interface. Define a fragment on the interface name, then use it in queries to fetch those shared fields from any implementing type.

Syntax

A fragment on an interface is defined using the fragment keyword followed by the fragment name, the on keyword, and the interface name. Inside the fragment, list the fields common to all types implementing the interface.

Use the fragment in a query by spreading it with ...FragmentName on a field that returns the interface type.

graphql

fragment CommonFields on Character {
  id
  name
}

query GetCharacters {
  characters {
    ...CommonFields
    ... on Human {
      height
    }
    ... on Droid {
      primaryFunction
    }
  }
}

Example

This example shows a GraphQL schema with an interface Character and two types Human and Droid implementing it. The fragment CharacterFields selects common fields id and name. The query uses this fragment to fetch those fields from all characters, plus type-specific fields.

graphql

schema {
  query: Query
}

type Query {
  characters: [Character]
}

interface Character {
  id: ID!
  name: String!
}

type Human implements Character {
  id: ID!
  name: String!
  height: Float
}

type Droid implements Character {
  id: ID!
  name: String!
  primaryFunction: String
}

fragment CharacterFields on Character {
  id
  name
}

query {
  characters {
    ...CharacterFields
    ... on Human {
      height
    }
    ... on Droid {
      primaryFunction
    }
  }
}

Output

{
  "data": {
    "characters": [
      {"id": "1", "name": "Luke Skywalker", "height": 1.72},
      {"id": "2", "name": "R2-D2", "primaryFunction": "Astromech"}
    ]
  }
}

Common Pitfalls

• Trying to use a fragment on an interface but including fields not defined in the interface causes errors.
• Forgetting to use inline fragments (... on TypeName) for fields specific to implementing types.
• Using fragments on concrete types when you want to reuse fields across multiple types.

graphql

fragment WrongFragment on Character {
  id
  name
  height  # Error: 'height' is not defined on interface Character
}

# Correct way:
fragment CorrectFragment on Character {
  id
  name
}

query {
  characters {
    ...CorrectFragment
    ... on Human {
      height
    }
  }
}

Quick Reference

Concept	Description	Example
Fragment on Interface	Defines reusable fields common to all implementing types	fragment FragName on InterfaceName { id name }
Using Fragment in Query	Spread fragment on interface field to get common fields	characters { ...FragName }
Inline Fragment	Select fields specific to a concrete type	... on Human { height }
Error Cause	Including fields not in interface in fragment	fragment Frag on Character { height }

Key Takeaways

Use fragments on interfaces to reuse common fields across multiple types.

Fragments on interfaces can only include fields defined in the interface.

Use inline fragments to fetch fields specific to implementing types.

Avoid including type-specific fields directly in interface fragments.

Fragments improve query readability and reduce repetition.