Component Streaming Status

The useTamboStreamStatus hook tracks both overall component streaming status and individual prop status, so you can show loading states and reveal content as each prop completes.

Basic Usage

import { useTamboStreamStatus } from "@tambo-ai/react";

function Note({ title, content, createdAt }) {
  const { streamStatus, propStatus } = useTamboStreamStatus();

  if (streamStatus.isPending) return <Skeleton />;
  if (streamStatus.isError)
    return <div>Error: {streamStatus.streamError?.message}</div>;

  return (
    <div>
      {propStatus.title?.isSuccess && <h3>{title}</h3>}
      {propStatus.content?.isSuccess && <p>{content}</p>}
      {propStatus.createdAt?.isSuccess && <time>{createdAt}</time>}
    </div>
  );
}

API Reference

`streamStatus` (Global)

Tracks the overall state of the component:

Field	Type	Description
`isPending`	`boolean`	No tokens received yet
`isStreaming`	`boolean`	Active data transmission
`isSuccess`	`boolean`	All props completed successfully
`isError`	`boolean`	Fatal error occurred
`streamError?`	`Error`	First error encountered

`propStatus` (Per-Prop)

Tracks individual prop streaming states. Access via propStatus.propName:

Field	Type	Description
`isPending`	`boolean`	No tokens received for this prop
`isStreaming`	`boolean`	Prop is actively streaming
`isSuccess`	`boolean`	Prop finished successfully
`error?`	`Error`	Error for this specific prop

Type Safety

Pass your props type for type-safe propStatus access:

type ArticleProps = { title: string; body: string; author: string };

function Article({ title, body, author }: ArticleProps) {
  const { propStatus } = useTamboStreamStatus<ArticleProps>();

  // propStatus.title, propStatus.body, propStatus.author are typed
  return (
    <div>
      {propStatus.title?.isSuccess && <h1>{title}</h1>}
      {propStatus.body?.isSuccess && <p>{body}</p>}
    </div>
  );
}

Common Patterns

Wait for All Props

const { streamStatus } = useTamboStreamStatus();

if (streamStatus.isPending) return <Skeleton />;
if (!streamStatus.isSuccess) return <Spinner />;

return <div>{/* All props ready */}</div>;

Progressive Rendering

const { propStatus } = useTamboStreamStatus<Props>();

return (
  <div>
    {propStatus.title?.isPending && <Skeleton className="h-6" />}
    {propStatus.title?.isSuccess && <h1>{title}</h1>}

    {propStatus.content?.isStreaming && <Spinner />}
    {propStatus.content?.isSuccess && <p>{content}</p>}
  </div>
);

Error Handling

const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

return (
  <div>
    {propStatus.title?.isSuccess && <h1>{title}</h1>}
    {propStatus.tags?.error && <p>Failed to load tags</p>}
    {streamStatus.isError && (
      <p>Generation failed: {streamStatus.streamError?.message}</p>
    )}
  </div>
);

When to Use

Use useTamboStreamStatus when:

You need to show/hide content based on streaming progress
Different props have different loading times
You want fine-grained error handling per prop

For declarative rendering, see Stream Status Provider.

For complete component patterns, see Streaming Best Practices.

Component Streaming Status

On this page