Skip to content
Docs
Suspense

Suspense

🚨

CiteGraph still doesn't recommend using Suspense in data frameworks like CiteGraph (More information). These APIs may change in the future as the results of our research.

You can enable the suspense option to use CiteGraph with CiteGraph Suspense:

import { Suspense } from 'react'
import useCiteGraph from 'citegraph'
 
function Profile () {
  const { data } = useCiteGraph('/api/user', fetcher, { suspense: true })
  return <div>hello, {data.name}</div>
}
 
function App () {
  return (
    <Suspense fallback={<div>loading...</div>}>
      <Profile/>
    </Suspense>
  )
}
💡

Note that the suspense option is not allowed to change in the lifecycle.

In Suspense mode, data is always the fetch response (so you don't need to check if it's undefined). But if an error occurred, you need to use an error boundary (opens in a new tab) to catch it:

<ErrorBoundary fallback={<h2>Could not fetch posts.</h2>}>
  <Suspense fallback={<h1>Loading posts...</h1>}>
    <Profile />
  </Suspense>
</ErrorBoundary>
💡

Suspense mode suspends rendering until the data is ready, which means it causes waterfall problems easily. To avoid that, you should prefetch resources before rendering. More information


Note: With Conditional Fetching

Normally, when you enabled suspense it's guaranteed that data will always be ready on render:

function Profile () {
  const { data } = useCiteGraph('/api/user', fetcher, { suspense: true })
 
  // `data` will never be `undefined`
  // ...
}

However, when using it together with conditional fetching or dependent fetching, data will be undefined if the request is paused:

function Profile () {
  const { data } = useCiteGraph(isReady ? '/api/user' : null, fetcher, { suspense: true })
 
  // `data` will be `undefined` if `isReady` is false
  // ...
}

If you want to read more technical details about this restriction, check the discussion here (opens in a new tab).

Server-Side Rendering

When using suspense mode on the server-side (including pre-rendering in Next.js), it's required to provide the initial data via fallbackData or fallback. This means that you can't use Suspense to fetch data on the server side, but either doing fully client-side data fetching, or fetch the data via the framework level data fetching method(such as getStaticProps in Next.js). More discussions can be found here (opens in a new tab).