Named Fragments for Field Reuse

Selection Sets That Drift Apart

Two screens need the same nine fields on User, so each query declares them:

query Profile { user(id: $id) { id name avatarUrl bio handle joinedAt location } }
query Sidebar { me { id name avatarUrl bio handle } }

The sidebar shipped first and stops at avatarUrl. Later the profile adds handle — and then a designer notices the sidebar header renders nothing, because a second copy of the field list nobody remembered is still missing it. Duplication across documents has no compiler watching it, so drift is the default outcome rather than an accident.

A named fragment collapses the copies:

fragment UserCard on User {
  id
  name
  avatarUrl
  bio
  handle
}

query Profile($id: ID!) {
  user(id: $id) { ...UserCard joinedAt location }
}

query Sidebar { me { ...UserCard } }

handle now has exactly one declaration, and every consumer picks it up on the next request. The fragment is still just a selection set: execution cost, resolver calls, and response shape are identical to writing those fields inline, because the server expands spreads before it runs anything. The win is purely in maintenance — one place to change, many places to benefit.

The same argument applies across a team. Once a field list is written twice, nobody can tell which copy is authoritative: code review approves one, a test exercises the other, and the fragment is the only structure that gives those fields a single owner.

Fragments also shrink reviews. Adding a field to UserCard is one line in one file; without fragments the same change is a diff in every query that renders a user, each needing its own reasoning about whether that screen wants the field at all — and that reasoning is exactly what gets skipped under time pressure.

Declare Once, Spread Anywhere

Spreads work inside any selection set, at any depth, including inside other fragments:

query Dashboard($id: ID!) {
  user(id: $id) {
    ...UserCard
    posts(first: 5) {
      ...PostPreview
      author { ...UserCard }    # same fragment, different path
    }
  }
}

Four validation rules are the ones you will actually hit:

1. The type condition must fit. Spreading fragment PostPreview on Post where the selection's type is User fails with Fragment cannot be spread here. A fragment declared on an interface or union may be spread wherever one of its members appears, which is what makes polymorphic reuse work.
2. Fragment names are unique per document. Two definitions named UserCard in one operation collide at validation, not at execution.
3. Every defined fragment must be used. An unused definition is a validation error, so dead fragments cannot survive a refactor quietly.
4. No fragment may reach itself. A fragment that spreads into itself through a nested field fails the no-cycles rule — see circular queries and cycle guards for why that rule exists.

Because spreads merge into the surrounding selection, fragments leave no trace in the JSON: the response contains the union of the fields, under the parent's own key. That property is what lets UserCard appear at the top level of one query and three levels deep in another while the client keeps reading a plain object.

One practical habit: fragments describe UI pieces ("what a user card renders"), not whole types. A fragment that selects everything on User reintroduces over-fetching under a new name.

Two consequences of merging are worth knowing before you refactor. First, fragments in the same selection set are checked by the ordinary field-merging rule: if two of them select posts with different limits, the document fails validation exactly as inline selections would, so shared fields belong in one definition rather than two overlapping ones. Second, a fragment can sit inside an inline fragment, which is how a polymorphic query reuses a concrete-type selection — see inline fragments.

Where Fragments Live in a Real Client

Two ownership models, both running in production codebases:

Whichever you pick, tooling reads the same documents. Codegen turns each fragment into a TypeScript type containing exactly the selected fields, so a UI change and its type change travel together — see TypeScript codegen. Normalized caches use fragment definitions when deciding whether a stored record can satisfy a query, which is why the same fragment drives rendering and cache reads — see response caching strategy.

When fragments stop helping:

• A three-field fragment used once is indirection, not reuse — inline it.
• One enormous fragment spread everywhere over-fetches again; scope fragments to components.
• Duplicating a fragment per variation is the drift problem returning. Conditional presence belongs to directives — see include and skip directives.
• Renaming or deleting a fragment changes generated types across every consumer; treat the fragment name as an interface.

Interview angle: explain why GraphQL's schema validation does not catch duplicated selection sets — validation checks each document in isolation, so two documents with divergent copies of the same selection both pass. Reuse is a project-level discipline, and fragments are the mechanism.

A naming rule keeps the strategy honest: name fragments after the component that renders them (UserCard), never after the type alone. Type-named fragments attract fields until they become the everything-fragment that both ownership models warn about, at which point every consumer over-fetches together.