GitHub - toss/suspensive: All-in-one for React Suspense — ErrorBoundary with shouldCatch, SSR-safe Suspense, Delay, and more

What is Suspensive?

React gives you Suspense, lazy, and an interface to build Error Boundaries — but using them in real applications reveals gaps. Suspensive fills those gaps with declarative components and hooks.

import { Delay, ErrorBoundary, ErrorBoundaryGroup, Suspense } from '@suspensive/react'

const Page = () => (
  <ErrorBoundaryGroup>
    <ErrorBoundaryGroup.Consumer>
      {({ reset }) => <button onClick={reset}>Reset All</button>}
    </ErrorBoundaryGroup.Consumer>
    <ErrorBoundary
      shouldCatch={NetworkError}
      fallback={({ error, reset }) => <ErrorUI error={error} onRetry={reset} />}
    >
      <Suspense
        clientOnly
        fallback={
          <Delay ms={200}>
            {({ isDelayed }) => <Spinner style={{ opacity: isDelayed ? 1 : 0, transition: 'opacity 200ms' }} />}
          </Delay>
        }
      >
        <Content />
      </Suspense>
    </ErrorBoundary>
  </ErrorBoundaryGroup>
)

shouldCatch — catch only specific error types, let others propagate
ErrorBoundaryGroup — reset multiple error boundaries at once, no prop drilling
clientOnly — SSR-safe Suspense that avoids hydration mismatches in Next.js
Delay — prevent flash-of-loading-state with render props for smooth fade-in
reset — built into the fallback props, no external state needed

Packages

Package	Description	Version
@suspensive/react	Suspense, ErrorBoundary, ErrorBoundaryGroup, Delay, ClientOnly
@suspensive/react-query	SuspenseQuery, SuspenseInfiniteQuery, Mutation, PrefetchQuery
@suspensive/jotai	Atom, AtomValue, SetAtom for Jotai integration
@suspensive/codemods	Automated migration codemods

Key Features

<ErrorBoundary/> with shouldCatch — catch only the errors you want (comparison with react-error-boundary)
<ErrorBoundaryGroup/> — reset multiple error boundaries at once, no prop drilling
<Suspense/> with clientOnly — SSR-safe Suspense that just works in Next.js
<SuspenseQuery/> — declarative data fetching as JSX, no hook constraints
<Delay/> — prevent flash-of-loading-state UX issues
<DefaultPropsProvider/> — set global default fallbacks for all components

Getting Started

npm install @suspensive/react

Visit suspensive.org for full documentation.

English | 한국어

Contributors

Read our Contributing Guide to familiarize yourself with Suspensive's development process, how to suggest bug fixes and improvements, and the steps for building and testing your changes.