Suspense

useSuspenseStream hands the initial hydration phase to <Suspense> and any non-streaming error to the nearest Error Boundary. It is a slim port that wraps useStream and leans on hydrationPromise to integrate with React's concurrent machinery.

Runnable example: The ui-react app in the streaming cookbook demonstrates the hydrate / reattach lifecycle this hook builds on — refresh mid-stream and the thread rehydrates before live events resume.

Basic usage

import { Suspense } from "react";
import { ErrorBoundary } from "react-error-boundary";
import { useSuspenseStream } from "@langchain/react";

function App() {
  return (
    <ErrorBoundary fallback={<ErrorDisplay />}>
      <Suspense fallback={<Spinner />}>
        <Chat />
      </Suspense>
    </ErrorBoundary>
  );
}

function Chat() {
  const { messages, submit, isStreaming } = useSuspenseStream({
    assistantId: "agent",
    apiUrl: "http://localhost:2024",
  });

  return (
    <>
      {messages.map((m, i) => (
        <div key={m.id ?? i}>{String(m.content)}</div>
      ))}
      {isStreaming && <TypingIndicator />}
    </>
  );
}

Behaviour:

• Initial hydration suspends. <Spinner /> renders until the first snapshot lands.
• Non-streaming errors (hydration failures, transport setup errors) throw and route to the nearest Error Boundary.
• Streaming errors still surface on stream.error so you can decide whether to re-throw or display inline.

Return shape

useSuspenseStream returns the same handle as useStream, with three differences:

All other fields (values, messages, toolCalls, interrupt / interrupts, subagents, submit, stop, respond, getThread, client, assistantId, …) work exactly as they do on useStream.

Thread switches

Changing the threadId prop re-suspends the component while the new thread hydrates. The existing Error Boundary and Suspense fallback handle the transition naturally:

<Suspense fallback={<Spinner />}>
  <Chat threadId={selectedThreadId} />
</Suspense>

A fresh hydrationPromise is installed internally on every threadId change; the suspended render resumes once it settles.

If you need manual control over hydration or don't want to involve React's concurrent machinery, use useStream and drive your own loading UI from isLoading / isThreadLoading / error / hydrationPromise.

API reference