Skip to content

docs: replace the concurrent mode note with a Suspense section #778

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tyler-reitz merged 2 commits into from
Aug 5, 2026
Merged

docs: replace the concurrent mode note with a Suspense section #778

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd23957
docs: replace the concurrent mode note with a Suspense section
tyler-reitz Aug 4, 2026
e1dba04
docs: describe SuspenseWithPerf's actual timing mechanism
tyler-reitz Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 7 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Firebase.
auth state, realtime data, and all other Firebase SDK events. Plus, they automatically unsubscribe when your component unmounts.
- **Access Firebase libraries from any component** - Need the Firestore SDK? `useFirestore`. Remote Config? `useRemoteConfig`.
- **Safely configure Firebase libraries** - Libraries like Firestore and Remote Config require settings like `enablePersistence` to be set before any data fetches are made. This can be tough to support in React's world of re-renders. ReactFire gives you `useInitFirestore` and `useInitRemoteConfig` hooks that guarantee they're set before anything else.
- **Optional `<Suspense>` support** - Hand loading states to React instead of checking a status yourself. Off by default, opt in with the `suspense` prop. See [Suspense](#suspense) below.

## Platform support

Expand Down Expand Up @@ -93,19 +94,16 @@ render(

This repository is maintained by Googlers but is not a supported Firebase product. Issues here are answered by maintainers and other community members on GitHub on a best-effort basis.

### Extra Experimental [concurrent mode](https://reactjs.org/docs/concurrent-mode-suspense.html) features
## Suspense

These features are marked as *extra experimental* because they use experimental React features that [will not be stable until sometime after React 18 is released](https://github.com/reactwg/react-18/discussions/47#:~:text=Likely%20after%20React%2018.0%3A%20Suspense%20for%20Data%20Fetching).
ReactFire's hooks can throw promises for [`<Suspense>`](https://react.dev/reference/react/Suspense) to catch, so React handles loading states for you instead of you checking `status` on each result.

- **Loading states handled by `<Suspense>`** - ReactFire's hooks throw promises
that Suspense can catch. Let React
[handle loading states for you](https://reactjs.org/docs/concurrent-mode-suspense.html).
- **Automatically instrument your `Suspense` load times** - Need to automatically instrument your `Suspense` load times with [RUM](https://firebase.google.com/docs/perf-mon)? Use `<SuspenseWithPerf />`.

Enable concurrent mode features by following the [concurrent mode setup guide](https://reactjs.org/docs/concurrent-mode-adoption.html#installation) and then setting the `suspense` prop in `FirebaseAppProvider`:
This is **off by default**. Opt in with the `suspense` prop on `FirebaseAppProvider`:

```jsx
<FirebaseAppProvider firebaseConfig={firebaseConfig} suspense={true}>
```

See concurrent mode code samples in [example/withSuspense](https://github.com/FirebaseExtended/reactfire/tree/main/example/withSuspense)
`<SuspenseWithPerf />` does the same and also measures how long the fallback was shown, using the browser's [User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/User_timing).

See [example/withSuspense](https://github.com/FirebaseExtended/reactfire/tree/main/example/withSuspense) for full samples.
Loading