Setting the file. One moment.
Subchapter 1.3
references/fragments.mdMarkdown22 KBView on GitHub
GraphQL fragments define a set of fields for a specific type. In Apollo Client, fragments are especially powerful when colocated with components to define each component’s data requirements independently, creating a clear separation of concerns and enabling better component composition.
A GraphQL fragment defines a set of fields for a specific GraphQL type. Fragments are defined on a specific GraphQL type and can be included in operations using the spread operator (...).
In Apollo Client, fragments serve a specific purpose:
Fragments are for colocation, not reuse. Each component should declare its data needs in a dedicated fragment. This allows components to independently evolve their data requirements without creating artificial dependencies between unrelated parts of your application.
Fragments enable:
import { gql } from "@apollo/client";
const USER_FRAGMENT = gql`
fragment UserFields on User {
id
name
email
avatarUrl
}
`;Every fragment includes:
UserFields)User)Include fragments in queries using the spread operator:
const GET_USER = gql`
query GetUser($id: ID!) {
user(id: $id) {
...UserFields
}
}
${USER_FRAGMENT}
`;When using GraphQL Code Generator with the recommended configuration (typescript, typescript-operations, and typed-document-node plugins), fragments defined in your source files are automatically picked up and generated into typed document nodes. The generated fragment documents already include the fragment definition, so you don’t need to interpolate them manually into queries.
Fragment colocation is the practice of defining fragments in the same file as the component that uses them. This creates a clear contract between components and their data requirements.
The recommended pattern for colocating fragments with components:
import { gql, FragmentType } from "@apollo/client";
import { useSuspenseFragment } from "@apollo/client/react";
// Fragment definition
// This will be picked up by Codegen to create `UserCard_UserFragmentDoc` in `./fragments.generated.ts`.
// As that generated fragment document is correctly typed, we use that in the code going forward.
// This fragment will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.
if (false) {
gql`
fragment UserCard_user on User {
id
name
email
avatarUrl
}
`;
}
// This has been created from above fragment definition by CodeGen and is a correctly typed `TypedDocumentNode`
import { UserCard_UserFragmentDoc } from "./fragments.generated.ts";
// Component receives the (partially masked) parent object
export function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
// Creates a subscription to the fragment in the cache
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
fragmentName: "UserCard_user",
from: user,
});
return (
<div>
<img src={data.avatarUrl} alt={data.name} />
<h2>{data.name}</h2>
<p>{data.email}</p>
</div>
);
}A suggested naming pattern for fragments follows this convention:
{ComponentName}_{propName}Where propName is the name of the prop the component receives containing the fragment data.
Examples:
UserCard_user - Fragment for the user prop in the UserCard componentPostList_posts - Fragment for the posts prop in the PostList componentCommentItem_comment - Fragment for the comment prop in the CommentItem componentThis convention makes it clear which component owns which fragment. However, you can choose a different naming convention based on your project’s needs.
Note: A component might accept fragment data through multiple props, in which case it would have multiple associated fragments. For example, a CommentCard component might accept both a comment prop and an author prop, resulting in CommentCard_comment and CommentCard_author fragments.
Parent components compose child fragments to build complete queries:
// Child component
import { gql } from "@apollo/client";
if (false) {
gql`
fragment UserAvatar_user on User {
id
avatarUrl
name
}
`;
}
// Parent component composes child fragments
if (false) {
gql`
fragment UserProfile_user on User {
id
name
email
bio
...UserAvatar_user
}
`;
}
// Page-level query composes all fragments
if (false) {
gql`
query UserProfilePage($id: ID!) {
user(id: $id) {
...UserProfile_user
}
}
`;
}This creates a hierarchy that mirrors your component tree.
Apollo Client provides hooks to read fragment data within components. These hooks work with data masking to ensure components only access the data they explicitly requested.
For components using Suspense and concurrent features:
import { useSuspenseFragment } from "@apollo/client/react";
import { FragmentType } from "@apollo/client";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
fragmentName: "UserCard_user",
from: user,
});
return <div>{data.name}</div>;
}For components not using Suspense:
import { useFragment } from "@apollo/client/react";
import { FragmentType } from "@apollo/client";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
const { data, complete } = useFragment({
fragment: UserCard_UserFragmentDoc,
fragmentName: "UserCard_user",
from: user,
});
if (!complete) {
return <div>Loading...</div>;
}
return <div>{data.name}</div>;
}The complete field indicates whether all fragment data is available in the cache.
Both hooks accept these options:
{
// The fragment document (required)
fragment: TypedDocumentNode,
// The fragment name (optional in most cases)
// Only required if the fragment document contains multiple definitions
fragmentName?: string,
// The source data containing the fragment (required)
// Can be a single object or an array of objects
from: FragmentType<typeof fragment> | Array<FragmentType<typeof fragment>>,
// Variables for the fragment (optional)
variables?: Variables,
}When from is an array, the hook returns an array of results, allowing you to read fragments from multiple objects efficiently. Note: Array support for the from parameter was added in Apollo Client 4.1.0.
Data masking is a feature that prevents components from accessing data they didn’t explicitly request through their fragments. This enforces proper data boundaries and prevents over-rendering.
Enable data masking when creating your Apollo Client:
import { ApolloClient, InMemoryCache } from "@apollo/client";
const client = new ApolloClient({
cache: new InMemoryCache(),
dataMasking: true, // Enable data masking
});With data masking enabled:
FragmentType objectsuseFragment or useSuspenseFragment to unmask dataWithout data masking:
// ❌ Without data masking - component can access any data from parent
function UserCard({ user }: { user: User }) {
// Can access any User field, even if not in fragment
return <div>{user.privateData}</div>;
}With data masking:
// ✅ With data masking - component can only access its fragment data
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
from: user,
});
// TypeScript error: 'privateData' doesn't exist on fragment type
// return <div>{data.privateData}</div>;
// Only fields from the fragment are accessible
return <div>{data.name}</div>;
}The fragment registry is an alternative approach to GraphQL Code Generator’s automatic fragment inlining by name. It allows you to register fragments globally, making them available throughout your application by name reference.
Important: GraphQL Code Generator automatically inlines fragments by name wherever they’re used in your queries. Either approach is sufficient on its own—you don’t need to combine them.
import { ApolloClient, InMemoryCache } from "@apollo/client";
import { createFragmentRegistry } from "@apollo/client/cache";
export const fragmentRegistry = createFragmentRegistry();
const client = new ApolloClient({
cache: new InMemoryCache({
fragments: fragmentRegistry,
}),
});Register fragments after defining them:
import { gql } from "@apollo/client";
import { fragmentRegistry } from "./apollo/client";
const USER_FRAGMENT = gql`
fragment UserFields on User {
id
name
email
}
`;
fragmentRegistry.register(USER_FRAGMENT);With colocated fragments:
import { fragmentRegistry } from "@/apollo/client";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
// Register the fragment globally
fragmentRegistry.register(UserCard_UserFragmentDoc);Once registered, fragments can be referenced by name in queries without explicit imports:
// Fragment is available by name because it's registered
const GET_USER = gql`
query GetUser($id: ID!) {
user(id: $id) {
...UserCard_user
}
}
`;There are three approaches to make child fragments available in parent queries:
GraphQL Code Generator inlining (Recommended): CodeGen automatically inlines fragments by name. No manual work needed—just reference fragments by name in your queries.
Fragment Registry: Manually register fragments to make them available by name. Useful for runtime scenarios where CodeGen isn’t available.
Manual interpolation: Explicitly import and interpolate child fragments into parent fragments:
import { CHILD_FRAGMENT } from "./ChildComponent";
const PARENT_FRAGMENT = gql`
fragment Parent_data on Data {
field
...Child_data
}
${CHILD_FRAGMENT}
`;GraphQL Code Generator inlining:
Fragment Registry:
Manual interpolation:
For most applications using GraphQL Code Generator (as shown in this guide), use the automatic inlining—it requires no additional setup and works seamlessly. Consider the fragment registry only if bundle size becomes a concern in applications with deeply nested component trees.
Apollo Client provides strong TypeScript support for fragments through GraphQL Code Generator.
GraphQL Code Generator produces typed fragment documents:
// Generated file: fragments.generated.ts
export type UserCard_UserFragment = {
__typename: "User";
id: string;
name: string;
email: string;
avatarUrl: string;
} & { " $fragmentName"?: "UserCard_UserFragment" };
export const UserCard_UserFragmentDoc: TypedDocumentNode<
UserCard_UserFragment,
never
>;Use FragmentType to accept masked fragment data:
import { FragmentType } from "@apollo/client";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
from: user,
});
// 'data' is fully typed as UserCard_UserFragment
return <div>{data.name}</div>;
}TypeScript infers types from fragment documents automatically:
import { UserCard_UserFragmentDoc } from "./fragments.generated";
// Types are inferred from the fragment
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
from: user,
});
// data.name is string
// data.email is string
// data.nonExistentField is a TypeScript errorWhen passing fragment data from parent to child:
// Parent query
const { data } = useSuspenseQuery(GET_USER);
// TypeScript ensures the query includes UserCard_user fragment
// before allowing it to be passed to UserCard
<UserCard user={data.user} />;Fragments are for colocation, not reuse. Each component should declare its data needs in a dedicated fragment, even if multiple components currently need the same fields.
Sharing fragments between components just because they happen to need the same fields today creates artificial dependencies. When one component’s requirements change, the shared fragment must be updated, causing all components using it to over-fetch data they don’t need.
// ✅ Good: Each component has its own fragment
if (false) {
gql`
fragment UserCard_user on User {
id
name
email
avatarUrl
}
`;
gql`
fragment UserListItem_user on User {
id
name
email
}
`;
}
// If UserCard later needs 'bio', only UserCard_user changes
// UserListItem doesn't over-fetch 'bio'// ❌ Avoid: Sharing a generic fragment across components
const COMMON_USER_FIELDS = gql`
fragment CommonUserFields on User {
id
name
email
}
`;
// UserCard and UserListItem both use CommonUserFields
// When UserCard needs 'bio', adding it to CommonUserFields
// causes UserListItem to over-fetch unnecessarilyThis independence allows each component to evolve its data requirements without affecting unrelated parts of your application.
Compose all page data requirements into a single query at the page level:
// ✅ Good: Single page-level query
if (false) {
gql`
query UserProfilePage($id: ID!) {
user(id: $id) {
...UserHeader_user
...UserPosts_user
...UserFriends_user
}
}
`;
}// ❌ Avoid: Multiple queries in different components
function UserProfile() {
const { data: userData } = useQuery(GET_USER);
const { data: postsData } = useQuery(GET_USER_POSTS);
const { data: friendsData } = useQuery(GET_USER_FRIENDS);
// ...
}Non-page components should use useFragment or useSuspenseFragment:
// ✅ Good: Component reads fragment data
import { FragmentType } from "@apollo/client";
import { useSuspenseFragment } from "@apollo/client/react";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
from: user,
});
return <div>{data.name}</div>;
}// ❌ Avoid: Component uses query hook
function UserCard({ userId }: { userId: string }) {
const { data } = useQuery(GET_USER, { variables: { id: userId } });
return <div>{data.user.name}</div>;
}Keep fragments minimal and only request fields the component actually uses:
// ✅ Good: Only necessary fields
if (false) {
gql`
fragment UserListItem_user on User {
id
name
}
`;
}// ❌ Avoid: Requesting unused fields
if (false) {
gql`
fragment UserListItem_user on User {
id
name
email
bio
friends {
id
name
}
posts {
id
title
}
}
`;
}The @defer directive allows you to defer loading of non-critical fields, enabling faster initial page loads by prioritizing essential data. The deferred fields are delivered via incremental delivery and arrive after the non-deferred data, allowing the UI to progressively render as data becomes available.
Defer slow fields that aren’t immediately visible:
if (false) {
gql`
query ProductPage($id: ID!) {
product(id: $id) {
id
name
price
...ProductReviews_product @defer
}
}
`;
}This allows the page to render quickly while reviews load in the background.
Use the @client directive for fields resolved locally:
if (false) {
gql`
fragment TodoItem_todo on Todo {
id
text
completed
isSelected @client
}
`;
}Always enable data masking in new applications:
const client = new ApolloClient({
cache: new InMemoryCache(),
dataMasking: true,
});This enforces proper boundaries from the start and prevents accidental coupling between components.
Apollo Client’s data masking and GraphQL Code Generator’s fragment masking are different features that serve different purposes:
GraphQL Code Generator’s fragment masking (when using the client preset) is a type-level feature:
useFragment hook simply “unmasks” the data on a type levelApollo Client’s data masking is a runtime feature with significant performance benefits:
useFragment and useSuspenseFragment hooks create cache subscriptions1. No Accidental Data Access
With runtime data masking, masked fields are not present in the parent object at all. You cannot accidentally access them, even if you bypass TypeScript type checking.
2. Fewer Re-renders
Apollo Client’s approach creates more efficient subscriptions:
useSuspenseFragment. When a masked field changes, only the child component that subscribed to it re-renders.import { FragmentType } from "@apollo/client";
import { useSuspenseQuery, useSuspenseFragment } from "@apollo/client/react";
import { UserCard_UserFragmentDoc } from "./fragments.generated";
function ParentComponent() {
const { data } = useSuspenseQuery(GET_USER);
// With Apollo Client data masking:
// - data.user only contains unmasked fields
// - Parent doesn't re-render when child-specific fields change
return <UserCard user={data.user} />;
}
function UserCard({
user,
}: {
user: FragmentType<typeof UserCard_UserFragmentDoc>;
}) {
// Creates a cache subscription specifically for UserCard_user fields
const { data } = useSuspenseFragment({
fragment: UserCard_UserFragmentDoc,
from: user,
});
// Only this component re-renders when these fields change
return <div>{data.name}</div>;
}This granular subscription approach improves performance in large applications with deeply nested component trees.