Fragments let you reuse common field selections across your GraphQL queries, reducing duplication and improving maintainability.
fragment Profile on User {
picture
name
}
Using Fragments
You can use fragments anywhere in your selection set, regardless of the entry point type. To use a fragment:
- Ensure it has a unique name within the request document
- Specify a type (Object, Interface, or Union)
- Select only fields present in that type
query {
me { ...Profile }
}
fragment Profile on User { picture name }
query {
me { picture name }
}
Fragment Type Constraints
Fragment types can be:
Multiple Fragment Usage
Currently, you cannot use a fragment that would be prepared more than once by multiple spreads. Put preparable fields inside the operation instead.
{ users { ...UserData } }
# ↳ Just one prepare OK
fragment UserData on User { id email addresses { id line1 } }
{ users { ...UserData } user(id: 1) { ...UserData } }
# ↳ First prepare OK ↳ Second prepare ERROR
fragment UserData on User { id email addresses { id line1 } }
# ↳ This causes the problem
{
users { ...UserData addresses { ...AddressData } }
user(id: 1) { ...UserData addresses { ...AddressData } }
}
fragment UserData on User { id email }
fragment AddressData on Address { id line1 }
Components and Fragments
As a best practice, front-end components should declare the fields they need for rendering. You can turn this into fragments to simplify your queries.
// Show my profile and my friends' profiles
// where Profile is a separated component
import Profile, { Fragment as ProfileFragment } from '@/components/profile';
const query = `
query {
me { ...Profile friends { ...Profile } }
}
${ProfileFragment}
`;
Automatic Field Deduplication
When composing multiple fragments with overlapping fields, GraphQL automatically deduplicates them:
query {
me { id ...Profile ...PersonalCard ...Recipient }
}
fragment Profile on User { picture name }
fragment PersonalCard on User { id name phone email }
fragment Recipient on User { id picture name email }
{
"data": {
"me": {
"id": "1",
"picture": "avatar.jpg",
"name": "John Doe",
"phone": "+15551239876",
"email": "[email protected]"
}
}
}
id, name, picture, and email appear in multiple fragments, each field is returned only once.
Fragment Best Practices
Name fragments clearly
Use descriptive names that indicate the fragment’s purpose, like UserProfile, AddressData, or ProductDetails.
Keep fragments focused
Each fragment should represent a logical grouping of fields for a specific component or use case.
Avoid deep nesting
While fragments can contain nested fields, avoid excessive nesting that makes them harder to reuse.
Co-locate with components
Store fragment definitions alongside the components that use them for better maintainability.
Fragments are especially powerful in component-based architectures where each component knows exactly which data it needs to render.