GraphQL Data Fetching in Practice: Fragments and Colocation

The plain-language idea

A GraphQL query and a REST endpoint solve the shape-of-data problem differently, but a real GraphQL codebase runs into a second problem that has nothing to do with over- or under-fetching: where does a query actually live?

The naive approach is one big query at the top of a page, listing every field every component in that page's tree needs:

query ProfilePage($id: ID!) {
  user(id: $id) {
    name
    avatarUrl
    bio
    followerCount
    joinedAt
  }
}

That works, until a component three levels deep needs a new field. Its own rendering code doesn't declare what data it needs — some unrelated file at the top of the tree does. Adding a field to a deeply nested component means going and finding that top-level query, editing it, and hoping you didn't also disturb a field some other component was relying on. This is a real, common source of "why is this field missing" bugs: the component's data requirement and the component's rendering code live in two different places that nobody keeps in sync on purpose.

Fragments fix this by letting each component declare its own data requirement, colocated with (defined right next to) the component that uses it:

fragment UserAvatarFields on User {
  name
  avatarUrl
}

See it in a real thing: a profile page built from colocated fragments

// UserAvatar.tsx — the fragment lives right next to the component that needs it
const UserAvatarFields = `
  fragment UserAvatarFields on User {
    name
    avatarUrl
  }
`;

function UserAvatar({ user }: { user: { name: string; avatarUrl: string } }) {
  return (
    <div>
      <img src={user.avatarUrl} alt={user.name} />
      <span>{user.name}</span>
    </div>
  );
}

// FollowerCount.tsx — a completely separate component, its own fragment
const FollowerCountFields = `
  fragment FollowerCountFields on User {
    followerCount
  }
`;

function FollowerCount({ user }: { user: { followerCount: number } }) {
  return <span>{user.followerCount} followers</span>;
}

# ProfilePage's query composes the fragments instead of listing raw fields
query ProfilePage($id: ID!) {
  user(id: $id) {
    ...UserAvatarFields
    ...FollowerCountFields
  }
}

The page-level query no longer lists name, avatarUrl, and followerCount directly — it just spreads in the fragments each child component already declared. If UserAvatar later needs to render a join date too, that change happens entirely inside UserAvatar.tsx: add the field to its own fragment, and it flows up into the composed query automatically. Nobody has to hunt down ProfilePage's query to make a change that's really about how one leaf component renders.

What people usually miss

Watch out

• Fragments don't reduce the number of network requests by themselves. The composed query still fires once, same as the naive version — the win is entirely in where the field list is authored and maintained, not in request count.
• A component that only reads props doesn't need to know about the query at all. Colocation means the component asking for avatarUrl is the same component rendering it — a purely presentational child further down the tree just receives whatever shape its parent's fragment already fetched.
• Deleting a component without deleting its fragment usage leaves an orphaned field in the composed query. Real GraphQL tooling can catch unused fragments, but the discipline of removing a fragment's field list when the component that owned it goes away doesn't happen automatically just by adopting fragments.
• Colocation is a convention enforced by team habit and tooling, not by the GraphQL spec itself. Nothing stops a team from writing one giant query anyway — the payoff only shows up if every component actually declares its own fragment consistently, not just some of them.

Why this matters in interviews

"How would you structure GraphQL queries in a large component tree?" is a real, practical question, and naming fragment colocation — data requirements living with the component that uses them, composing upward into one query — is what separates a candidate who's actually maintained a GraphQL codebase from one who's only used it to fetch a single flat object.