Developers / React / Fetch Data

Fetch Data

In this article, you'll learn how to perform different queries to the Prismic API to get content in your React application.

Before you proceed

First, you'll need a project with React and Prismic. If you don't have one yet, start with the Install step.

Perform a query

The Prismic integration provides hooks for querying, which automatically use the client registered in <PrismicProvider>.

Here's what a basic query looks like:

Copy
import { PrismicRichText, useFirstPrismicDocument } from '@prismicio/react'

function App() {
  const [document] = useFirstPrismicDocument()

  return (
    <div>
      {document && (
        <PrismicRichText field={document.data.example_rich_text} />
      )}
    </div>
  )
}

Query helpers

Here are the most commonly-used query helper hooks:

usePrismicDocumentByUID()

Copy
usePrismicDocumentByUID(type, uid)
usePrismicDocumentByUID(type, uid, params)

Queries a document from the Prismic repository with a UID and Custom Type. type refers to the API ID of the Custom Type.

For example, here we are querying for a post document with a UID of my-first-post.

Copy
const [document] = usePrismicDocumentByUID('post', 'my-first-post')

useSinglePrismicDocument()

Copy
useSinglePrismicDocument(type)
useSinglePrismicDocument(type, params)

Queries a singleton document from the Prismic repository for a specific Custom Type. type refers to the API ID of the Custom Type.

For example, here we are querying for the only document of the Custom Type homepage.

Copy
const [document] = useSinglePrismicDocument('homepage')

useAllPrismicDocumentsByType()

Copy
useAllPrismicDocumentsByType(type)
useAllPrismicDocumentsByType(type, params)

Queries all documents from the Prismic repository for a specific Custom Type. type refers to the API ID of the Custom Type. This method may perform multiple network requests. It returns an array containing all matching documents from the repository.

For example, here we are querying for all documents of the Custom Type article.

Copy
const [documents] = useAllPrismicDocumentsByType('article')

Further Learning

There are many more methods for querying the API. All of these queries can accept options to filter, sort, paginate, and translate your query response. See them all in the @prismicio/react Technical Reference.

Use cases

Here are a few common use cases.

Query a nav menu or config document

In Prismic, you can create a singleton Custom Type to store site components, like a header, footer, nav menu, or SEO configuration.

To query a singleton, use the useSinglePrismicDocument() hook with the API ID of the singleton Custom Type.

Copy
import { useSinglePrismicDocument } from '@prismicio/react'

function App() {
  const [menu] = useSinglePrismicDocument('menu')

  // Use `menu` in your component's return value
}

Query one instance of a repeatable document

On repeatable documents, we recommend adding a UID field — a unique identifier. Prismic formats each document's UID so it is URL-friendly and unique to its Custom Type.

To query a specific document of a given Custom Type, like a blog post, you can use the usePrismicDocumentByUID() hook. To use usePrismicDocumentByUID(), pass the UID and the API ID of the Custom Type.

Copy
import { usePrismicDocumentByUID } from '@prismicio/react'

function App() {
  const [page] = usePrismicDocumentByUID('page', 'hello-world')

  // Use `page` in your component's return value
}

Query all documents

There are three common ways to get all documents.

  • You can query all documents of a certain type with useAllPrismicDocumentsByType() (recommended).
  • You can query a paginated list of all documents from your repository, regardless of type, using usePrismicDocuments(). This will return a paginated response, including the first 100 documents.
  • To query an unpaginated list of all documents regardless of type, use useAllPrismicDocumentsDangerously(). Since the payload can be large, this method can cause performance issues, and it is not recommended.
Copy
import { useAllPrismicDocumentsByType } from '@prismicio/react'

function App() {
  const [pages] = useAllPrismicDocumentsByType('page')

  // Use `pages` in your component's return value
}

Query by language

Prismic allows you to publish your content in different languages. By default, the API will return content in your master language. To get content in a different language, add an options object with a lang option and a locale code.

Here's an example of how to query the document of the type homepage in French (fr-fr).

Copy
import { useSinglePrismicDocument } from '@prismicio/react'

function App() {
  const [homepage] = useSinglePrismicDocument('homepage', {
    lang: 'fr-fr',
  })

  // Use `homepage` in your component's return value
}

Display a loading message

Every query hook returns its loading status alongside the query result. You can access the status by destructuring it from the second element of a hook's return value.

Here's an example using a hook's status to display a loading message.

Copy
import { usePrismicDocumentByUID } from '@prismicio/react'

function App() {
  const [page, { state }] = usePrismicDocumentByUID('page', 'hello-world')

  return (
    <div>
      {state === 'loading' ? (
        <p>Loading…</p>
      ) : (
        page && <p>{page.data.example_field}</p>
      )}
    </div>
  )
}

Further Learning

There are other states for querying hooks, such as when a query has completed or failed. See them all in the @prismicio/react Technical Reference.

← Previous

Install Prismic

Next →

Template Content

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.