Fragments

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

Here we will discuss Fragments and how you can use them in your Prismic/Gatsby project.

What are Fragments?

Fragments are an easy way to reuse parts of a GraphQL query and break your complex queries down into smaller, more easily managed components. This not only allows you to make your queries easier to read and understand, but can also allow you to define the fields you need for a specific component in that particular component's code.

Let's take a look at how this is done.

The basics of a fragment

Let's take a look at a simple fragment so that we can get an understanding of all the pieces. Here is a fragment that will retrieve some author content:

Copy
fragment AuthorInfo on PRISMIC_Page {
  author_name
  author_image
}

A fragment consists of three pieces:

  1. AuthorInfo - This is the name of the fragment that will use as a reference as shown in the next section. This can be whatever name makes most sense for your collection of fields.
  2. PRISMIC_Page - This is a specific GraphQL type. This is required and will need to match the type of the object where the fragment will be used. This is to make sure that your query is valid and that the fields you are trying to receive actually exist on the object.
  3. author_name and author_image - The last piece is the fields that you include in your fragment. This will look and work just like the body of a normal query. You can define any fields for the given type and have multiple levels of nesting. In our case above we are retrieving two fields with information about the author.

Using fragments in your project

Let's take a look at what this might look like in your Gatsby project. Continuing our example above here's a component that will display some author information on a page:

Copy
// src/components/author.js
import React from 'react'
import { graphql } from 'gatsby'

const Author = ({ author_name, author_image }) => {
  return (
    <>
      <h3>{author_name}</h3>
      <img src={author_image.url} alt={author_image.alt} />
    </>
  )
}

export const query = graphql`
fragment AuthorInfo on PRISMIC_Page {
  author_name
  author_image
}
`

export default Author

Now let's import this Author component and fragment into our Page component. When you import the Author component, you'll be able to use the fragment in the GraphQL query. Take a look at how we include the AuthorInfo fragment below:

Copy
// src/pages/page.js
import React from 'react'
import { graphql } from 'gatsby'
import Author from '../components/author'

const Page = ({ data }) => {
  const document = data.prismic.page

  return (
    <>
      {document.title}
      <Author
        author_name={document.author_name}
        author_image={document.author_image}
      />
      {document.description}
    </>
  )
}

export const query = graphql`
query PageQuery {
  prismic {
    page(uid: "example-page", lang: "en-us") {
      title
      description
      ...AuthorInfo
    }
  }
}
`

export default Page

Gatsby & GraphQL is smart enough to know what the AuthorInfo fragment is and include those fields in the main query.

When to use fragments

As mentioned above, fragments are a great way to define the fields you need in your GraphQL query in the component file that they will eventually be used in. Similar to our Author example above, if a component uses a number of content fields, it might be better to define them in the component file using a fragment. Slices and the Slice Zone components are great examples of where fragments can really shine.

More resources

If you want to learn more about Fragments here are some more resources for you to explore: