Tambo AI Documentation

The TamboPropStreamProvider uses a compound component pattern to manage streaming state. You wrap your content with the main provider and use its sub-components to define what renders at each streaming stage.

basic-usage.tsx

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

function WeatherCard({ location, temperature, condition }) {
  return (
    <TamboPropStreamProvider>
      <TamboPropStreamProvider.Pending>
        <div>Loading weather...</div>
      </TamboPropStreamProvider.Pending>
      <TamboPropStreamProvider.Success>
        <div>
          <h2>{location}</h2>
          <p>
            {temperature}°C, {condition}
          </p>
        </div>
      </TamboPropStreamProvider.Success>
    </TamboPropStreamProvider>
  );
}

Why Use the Stream Status Provider?

Declarative rendering - Use compound components to define what shows in each state
Per-prop tracking - Handle individual prop streaming (e.g., show title while body loads)
Enhanced UX - Add highlighting, animations, or transitions during streaming

Building on Previous Concepts

This guide builds on Streaming and Component Streaming Status. We recommend reading those first.

API Reference

Compound Components

<TamboPropStreamProvider.Pending /> - Renders when the stream is pending (no data yet)

<TamboPropStreamProvider.Streaming /> - Renders when the stream is actively streaming data

<TamboPropStreamProvider.Success /> - Renders when data is successfully received and complete

useTamboStream Hook

Access the stream context within the provider:

const { data, streamStatus, getStatusForKey } = useTamboStream();

useTamboStream Hook

The useTamboStream hook provides access to the stream context within the provider.

Usage Examples

Per-Prop Streaming

Track individual properties using the streamKey prop to show content progressively:

per-property-streaming.tsx

function ArticleCard({ title, summary }) {
  return (
    <TamboPropStreamProvider>
      <TamboPropStreamProvider.Streaming streamKey="title">
        <div>Loading title...</div>
      </TamboPropStreamProvider.Streaming>
      <TamboPropStreamProvider.Success streamKey="title">
        <h2>{title}</h2>
      </TamboPropStreamProvider.Success>

      <TamboPropStreamProvider.Streaming streamKey="summary">
        <div>Loading summary...</div>
      </TamboPropStreamProvider.Streaming>
      <TamboPropStreamProvider.Success streamKey="summary">
        <p>{summary}</p>
      </TamboPropStreamProvider.Success>
    </TamboPropStreamProvider>
  );
}

Error Handling and All States

Handle all possible streaming states including errors and empty states:

complete-error-handling.tsx

function RobustComponent({ data }) {
  const { streamStatus } = useTamboStreamStatus();

  return (
    <TamboPropStreamProvider>
      <TamboPropStreamProvider.Streaming>
        <div>AI is generating content...</div>
      </TamboPropStreamProvider.Streaming>

      <TamboPropStreamProvider.Pending>
        <div>No content generated yet</div>
      </TamboPropStreamProvider.Pending>

      <TamboPropStreamProvider.Success>
        <div>{data.content}</div>
      </TamboPropStreamProvider.Success>

      {streamStatus.isError && (
        <div>Error: {streamStatus.streamError?.message}</div>
      )}
    </TamboPropStreamProvider>
  );
}

Real-Time Streaming with Fallbacks

Show streaming values immediately as they arrive with controlled fallbacks:

real-time-streaming.tsx

function StreamingTextGenerator({ content, title, metadata }) {
  return (
    <TamboPropStreamProvider>
      <TamboPropStreamProvider.Streaming streamKey="title">
        <h1>{title || "Generating title..."}</h1>
      </TamboPropStreamProvider.Streaming>
      <TamboPropStreamProvider.Success streamKey="title">
        <h1>{title}</h1>
      </TamboPropStreamProvider.Success>

      <TamboPropStreamProvider.Streaming streamKey="content">
        <p>{content || "AI is writing..."}</p>
      </TamboPropStreamProvider.Streaming>
      <TamboPropStreamProvider.Success streamKey="content">
        <p>{content}</p>
      </TamboPropStreamProvider.Success>

      <TamboPropStreamProvider.Success streamKey="metadata">
        <div>
          <span>Generated: {metadata.timestamp}</span>
          <span>Words: {metadata.wordCount}</span>
        </div>
      </TamboPropStreamProvider.Success>
    </TamboPropStreamProvider>
  );
}

Custom Animations

Add visual feedback during streaming:

custom-animations.tsx

<TamboPropStreamProvider.Streaming streamKey="title">
  <div className="animate-pulse">Loading title...</div>
</TamboPropStreamProvider.Streaming>

<TamboPropStreamProvider.Success streamKey="title">
  <h2 className="transition-opacity">{title}</h2>
</TamboPropStreamProvider.Success>

Stream Status Provider

On this page