
<p>Whether you&#8217;re just getting started with building GraphQL applications or you&#8217;ve done it for years, you probably have a decent understanding of&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/" rel="noreferrer noopener">what GraphQL queries are</a>. But what about GraphQL fragments?&nbsp;</p>



<p>&nbsp;In this article, we&#8217;ll delve into some common use-cases where fragments shine, learn how to get the most out of them, and hopefully, I&#8217;ll inspire you to use more fragments in your GraphQL queries.</p>



<h2 class="wp-block-heading"><a href="#use-case-modeling-a-list" aria-hidden="true" class="aal_anchor" id="use-case-modeling-a-list"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Use case: modeling a list</h2>



<p>When you build a GraphQL-based application, the typical choice pattern is to start with building components — brilliantly simple UI components — that declare their data needs of which you can fetch using GraphQL queries. After a few data loading wins, you&#8217;re ready for something a little bit more complex — the infamous <em>List</em> component. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">export function SimpleGroceryList() {
  const { data } = useQuery(gql`
    query SimpleGroceryListQuery {
      groceries {
        id
        name
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;li key={grocery.id}&gt;
          {grocery.name}
        &lt;/li&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>As shown above, we can write a single query that fetches the entire list, and for each item, we get back the id and name. Now, sometimes this is about all you need. Other times, though, rendering a list item is not so simple, and before long, we&#8217;re asking ourselves an age-old question:&nbsp;<em>should the list item be a separate componen</em>t?&nbsp;</p>



<h3 class="wp-block-heading"><a href="#refactoring-to-list-items" aria-hidden="true" class="aal_anchor" id="refactoring-to-list-items"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Refactoring to list items</h3>



<p>We need to be aware of a tipping point here. When the complexity of the markup begins to hurt your head, keeping a stronger separation of concerns can be hugely beneficial (this doesn&#8217;t just apply to lists, but also any parent/child relationship in your render tree). The example we present here as a demonstration is relatively light, but we&#8217;ve seen some pretty gnarly scenarios. Let&#8217;s refactor this into two components. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// item
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// list
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<h3 class="wp-block-heading"><a href="#refactoring-to-separate-files" aria-hidden="true" class="aal_anchor" id="refactoring-to-separate-files"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Refactoring to separate files</h3>



<p>We might tolerate these two components sharing the same file at first, but as complexity scales up, it often becomes harder to maintain without refactoring GroceryListItem into its own file.&nbsp;</p>



<p> We now have GroceryListItem.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



<p>And we have the cleaner GroceryList component as well.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryList.jsx
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>While this separation of the parent and child component reduces clutter, it comes with two slight disadvantages we need to address.</p>



<h3 class="wp-block-heading"><a href="#disadvantage-1-undiscoverable-data-dependencies" aria-hidden="true" class="aal_anchor" id="disadvantage-1-undiscoverable-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Disadvantage #1 — Undiscoverable data dependencies</h3>



<p>Once we split the files apart, we lose the ability to scan the GraphQL query and compare it with the usage of the data in our UI code. So what can we do?&nbsp;</p>



<p> In the early days of React, to clarify the data dependencies of GroceryListItem, we might try addressing this with “PropTypes”. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// re-describe our component&#039;s data dependencies
GroceryItemList.propTypes = {
  grocery: PropTypes.shape({
    name: PropTypes.string.isRequired,
    quantity: PropTypes.number.isRequired,
  }).isRequired,
};</code></pre>



<p>PropTypes work, but it also exposes another disadvantage: duplicating data dependencies.</p>



<h3 class="wp-block-heading"><a href="#disadvantage-2-duplicating-data-dependencies" aria-hidden="true" class="aal_anchor" id="disadvantage-2-duplicating-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Disadvantage #2 — Duplicating data dependencies</h3>



<p>Regardless of if you&#8217;re using PropTypes or TypeScript to define component props, we still have a lot of typing to do. We&#8217;re duplicating the shape of our component&#8217;s data in two places: first in the GraphQL query and again in the component&#8217;s property list, which indeed makes fingers tired.</p>



<h2 class="wp-block-heading"><a href="#fragments-to-the-rescue" aria-hidden="true" class="aal_anchor" id="fragments-to-the-rescue"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Fragments to the rescue</h2>



<p>At their core,&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/react/data/fragments/" rel="noreferrer noopener">GraphQL fragments</a>&nbsp;are just small pieces (or &#8220;fragments&#8221;) of a larger GraphQL query. But how can they help us in this situation?</p>



<h3 class="wp-block-heading"><a href="#express-child-component-data-dependencies" aria-hidden="true" class="aal_anchor" id="express-child-component-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Express child component data dependencies</h3>



<p>With fragments, we can bring back the benefits of co-locating our data dependencies with our UI code, but in a more distributed way across the application. In the following code, we define a fragment with only the data that we need and export it for inclusion in the parent query. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryItemList.tsx

export const groceryListItemFragment = gql`
  fragment GroceryListItemFragment on Grocery {
    name
    quantity
  }
`;

/**
 * Automatically generated fragment type (you don&#039;t have to type this!)
 *
export interface GroceryListItemFragment {
  name: string;
  quantity: number;
}
*/

interface Props {
  grocery: GroceryListItemGroceryFragment;
}

export function GroceryListItem({ grocery }: Props) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



<h3 class="wp-block-heading"><a href="#less-typing-no-duplication" aria-hidden="true" class="aal_anchor" id="less-typing-no-duplication"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Less typing, no duplication</h3>



<p>Not only do fragments act as a way to express data dependencies, but&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/tooling/apollo-codegen/typescript-graphql-code-generator-generate-graphql-types/" rel="noreferrer noopener">using Apollo codegen</a>, we can type the data dependencies once and auto-generate Typescript types to ensure we pass the exact shape of data we need.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#detect-breaking-api-changes" aria-hidden="true" class="aal_anchor" id="detect-breaking-api-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Detect breaking API changes</h3>



<p>We automatically generate typings using the schema from our GraphQL API.&nbsp;</p>



<p>If we take advantage of a schema repository like the one provided through Apollo Studio, we can generate your types for our queries against whichever graph variant you need.&nbsp;</p>



<p>The auto-generated typings are useful because we can run `apollo codegen:generate` in the CI to ensure that all of the queries and fragments we&#8217;re requesting are available in the API when the code goes live.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="570" height="696" src="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png" alt="" class="wp-image-7539" srcset="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png 570w, https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks-246x300.png 246w" sizes="(max-width: 570px) 100vw, 570px" /></figure>



<p>To get started with&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/studio/schema-checks/" rel="noreferrer noopener">schema checks</a>&nbsp;and several other free GraphQL tools to help you build better, safer, and faster, register your graph @&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">https://studio.apollographql.com/dev</a>.</p>



<h3 class="wp-block-heading"><a href="#using-fragments-in-parent-components" aria-hidden="true" class="aal_anchor" id="using-fragments-in-parent-components"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using fragments in parent components</h3>



<p>Going back to our example, in the parent list component, we import the fragment into our query and fetch the data for each grocery item as before.&nbsp;</p>



<p>Notice that we also request the id field in addition to GroceryListItemFragment , clarifying that GroceryList has a dependency on id but no other fields.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// GroceryList.tsx

import { groceryListItemFragment, GroceryListItem } from &#039;./GroceryListItem&#039;;

export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        ...GroceryListItemFragment // fragment is &quot;spread&quot; here
      }
    }
    ${groceryListItemFragment} // also include the fragment definition in the query
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p>Nice! What happens if we decide to add another piece of information to the list item? We modify our fragment definition, re-run code generation, and voila — and we have updated our strong types. We&#8217;ve also maintained the separation of concerns between fetching the list and describing how we render an item.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>When we started building&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">Apollo Studio&#8217;s</a>&nbsp;frontend application, it was way back in the early days of React 14. We were making heavy use of GraphQL but still figuring out best practices. As our codebase began to expand in scope and complexity, we started to develop more scalable patterns and developed many new strategies for weaving together GraphQL, Typescript, and UI functionality. Some of the big lessons were the many benefits that fragments provide:</p>



<ul class="wp-block-list"><li>Declaring fragments alongside UI code allows you to separate concerns between parent components and children.</li><li>Defining and exporting fragments makes components more re-usable since data dependencies are expressively declared, and parents can compose as needed.</li><li>Using fragments allows you to make a single query to fetch data for multiple components at once, reducing the need for repeated round-trips to the server.</li><li>Automatic type generation FTW. Strict build-time checking prevents bugs before they happen; codegen eliminates duplication of code to describe data shapes across the component boundary.</li></ul>



<p>Hopefully, this helps solve some problems that you might have in your codebase. Thanks for reading!</p>


GraphQL

Using GraphQL Fragments for safer, cleaner, and faster code

Stay in our orbit