Query Basics

On this page, you'll learn how to query and display documents from your Prismic repository to your website using the Gatsby source plugin.


Basic query syntax

The first step to getting content from your Prismic repository is to query Gatsby's GraphQL API. The GraphQL schema of the Prismic and Gatsby plugin gives you two options to write your queries; where ${CustomType} is the API ID of your document's Custom Type:

  1. prismic${CustomType}: Queries a single document of a given type with optional filtering parameters.
  2. allPrismic${CustomType}: Queries all documents of a given type.

Now, we will detail when to use one option or the other.

Query repeatable types

Use the prismic${CustomType} syntax with variables to query documents of a repeatable Custom Type and generate page queries dynamically.

Or, use the allPrismic${CustomType} syntax if you need to retrieve all the documents of a repeatable Custom Type at once.

See the following examples:

  • prismic${CustomType}
  • allPrismic${CustomType}
Copy
query PageQuery ($id: String) {
  prismicPage(id: {eq: $id}) {
    data {
      document_title {
        text
      }
    }
  }
}
Copy
query BlogPostList {
  allPrismicBlogPost {
    nodes {
      data {
        document_title {
          text
        }
      }
    }
  }
}

Query single types

When you want to query a single type document, or create a single page, use the prismic${CustomType} syntax to get the unique instance. See the following example:

Copy
query Homepage {
  prismicHomepage {
    data {
      document_title {
        text
      }
    }
  }
}

Page vs. component queries

Page queries are made inside the /pages or /templates folders. These queries populate your page templates with the data you need for each page.

Component queries are used in reusable components; you can use useStaticQuery to create more modular queries.

We recommend you use Fragments. This will allow you to make the Slice queries individual to their components. And therefore, the page queries will be more readable. This is particularly helpful when the query retrieves many Slices in a Custom Type.

Structure of the API response

After doing your queries, this is the format you'll receive from the API for your Single and Repeatable documents. Here are truncated examples of API responses containing a few fields and one Slice:

  • Multiple documents
  • Single Document
Copy
{
  "data": {
    "allPrismicPage": {
      "nodes": [
        {
          "data": {
            "example_date": "2020-12-10",
            "example_timestamp": "2020-12-10T04:05:09+0000",
            "example_color": "#c7ab5d",
            "example_number": 74.5,
            "example_key_text": "Example Key Text Value",
            "example_select": "North",
            "example_boolean": true,
            "body": [
              {
                "primary": {
                  "slice_type": "quote",
                  "quote": {
                    "raw": [
                      {
                        "type": "paragraph",
                        "text": "Etiam pellentesque mauris ut lectus",
                        "spans": []
                      }
                    ]
                  }
                }
              },
              // ... other Slices
            ]
          }
        },
        // ... other documents
      ]
    }
  }
}
Copy
{
  "data": {
    "prismicHomepage": {
      "data": {
        "example_date": "2020-12-10",
        "example_timestamp": "2020-12-10T04:05:09+0000",
        "example_color": "#c7ab5d",
        "example_number": 74.5,
        "example_key_text": "Example Key Text Value",
        "example_select": "North",
        "example_boolean": true,
        "body": [
          {
            "primary": {
              "slice_type": "quote",
              "quote": {
                "raw": [
                  {
                    "type": "paragraph",
                    "text": "Etiam pellentesque mauris ut lectus",
                    "spans": []
                  }
                ]
              }
            }
          }
         // ... other Slices
        ]
      }
    }
  }
}

Save the response

To retrieve the response from a query, access the data from a page or component's props. Save it in a variable; we usually name it document. See the following examples:

  • Multiple documents
  • Single document
Copy
const documents = data.allPrismicPages.nodes
Copy
const document = data.prismicAuthor

Full usage example

Take a look at how we save and use the response in the following examples.

In the Layout.js component, we query the menu that'll appear at the top of all pages. In the PostList.js component, we query for all documents of the type blog to create a list of posts. And in the {PrismicAuthor.url}.js page, we query the data for each dynamic Author page:

  • {PrismicAuthor.url}.js
  • Layout.js
  • PostList.js
Copy
// Example {PrismicAuthor.url}.js file

import React from 'react'
import { graphql } from 'gatsby'
import { Layout } from '../components/layout'
import { PostList } from '../components/PostList'

export const AuthorTemplate = ({ data }) => {
  if (!data) return null
  const document = data.prismicAuthor
  return (
    <Layout>
      <h1>{document.data.author_name.text}</h1>
      <PostList />
    </Layout>
  )
}

export const query = graphql`
  query Author($id: String) {
    prismicAuthor(id: { eq: $id }) {
       data {
         author_name {
          text
        }
      }
    }
  }
`

export default AuthorTemplate
Copy
// Example Layout.js file

import React from 'react'
import { Link, graphql, useStaticQuery } from 'gatsby'

export const Layout = ({ children }) => {
  const data = useStaticQuery(graphql`
    {
      prismicMenu {
        data {
          group_with_links {
            author {
              url
            }
            link_label {
              text
            }
          }
        }
      }
    }
  `)

  const document = data.prismicMenu
  return (
    <>
      <header>
        <ul>
          {document.prismicMenu.data.group_with_links.map((link, i) => {
            <li>
              <Link to={link.author.url}>{link.link_label.text}</Link>
            </li>
          })}
        </ul>
      </header>
      <main>{children}</main>
    </>
  )
}
Copy
// Example PostList.js file

import React from 'react'
import { graphql, useStaticQuery } from 'gatsby'

export const PostList = () => {
  const data = useStaticQuery(graphql`
    {
      allPrismicBlogpost {
        nodes {
          data {
            post_title {
              text
            }
          }
        }
      }
    }
  `)

  const documents = data.allPrismicBlogpost.nodes
  return (
    <div>
      <ul>
        {documents.map((item, i) => {
          return <li key={i}>{item.data.post_title.text}</li>
        })}
      </ul>
    </div>
  )
}

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.