• ✨ Features
• 🚀 Example
• 📚 Documentation
• License

react-use-suspense provides a very simple and lightweight useSuspense hook to use the Suspense API with any async function.

✨ Features

• Suspense for new versions of React
• Dependency array (like useEffect)
• TypeScript ready
• Minimal footprint (1kB gzipped)

🚀 Example

function Component() {
  const data = useSuspense('data', async () => {
    // ...
    return 'Hello world'
  })

  return <p>{data}</p>
}

function App() {
  return (
    <Suspense fallback="Loading...">
      <Component />
    </Suspense>,
  )
}

📚 Documentation

Basics

Import the useSuspense hook from react-use-suspense. This hook accepts a key that must be unique to the data you want to fetch, and an async function that returns this data:

import { useSuspense } from 'react-use-suspense'

function Component() {
  const data = useSuspense('unique-key', async () => {
    // ...
    return 'Hello world'
  })
}

When you need to use this component, simply wrap it inside a Suspense component and provide a fallback prop:

function App() {
  return (
    <Suspense fallback="Loading...">
      <Component />
    </Suspense>,
  )
}

Dependency array

Similar as the useEffect, useMemo, useCallback... hooks, you can pass a third argument as known as a dependency array. Whenever one of the dependency in this array changes, the async function will re-run:

function Component({ name }) {
  const data = useSuspense('unique-key', async () => {
    // ...
    return 'Hello: ' + name
  }, [name]) // Will trigger when name changes
}

Options

As the fourth argument, you can pass an optionnal object of options:

keepPreviousValue

This option will make sure to not trigger a Suspense when the async function re-runs. This is the default behavior, and you can disable to always trigger a Suspense:

const data = useSuspense('unique-key', async () => {
  // ...
  return 'Hello: ' + name
}, [name], {
  keepPreviousValue: false
})

equalFn

You can provide a custom equality function that is used to compare old and new dependency arrays.

const data = useSuspense('unique-key', async () => {
  // ...
  return 'Hello world'
}, [], {
  // This is the default one
  equalFn: (a, b) => JSON.stringify(a) === JSON.stringify(b)
})

Alternatively, you can update these options globally if you always want to have those behaviors:

import { setKeepPreviousValue, setEqualFn } from 'react-use-suspense'

setKeepPreviousValue(false)
setEqualFn((a, b) => JSON.stringify(a) === JSON.stringify(b))

License

MIT