# Component Streaming Status
URL: /concepts/streaming/component-streaming-status

The `useTamboStreamStatus` hook lets you track both overall and per-prop streaming status, so you can show loading or completed states for each prop as they arrive.

## How Does It Work?

Without per-prop tracking, you're forced to show nothing until all props are ready (poor UX) or show everything with default values (potentially confusing). This hook gives you granular control over what renders when.

```tsx title="basic-usage.tsx"
import { useTamboStreamStatus } from "@tambo-ai/react";

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

  // Wait for everything to complete
  if (!streamStatus.isSuccess) return <Spinner />;

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

<Callout type="info" title="Building on Previous Concepts">
  This guide builds on **[Streaming](/concepts/streaming)** and **[Response
  Component Streaming](/concepts/streaming/response-component-streaming)**. We
  recommend reading those first.
</Callout>

## Status Types

### Global Stream Status (`streamStatus`)

Tracks the overall state of the entire component:

| Field          | Type      | Description                                              |
| -------------- | --------- | -------------------------------------------------------- |
| `isPending`    | `boolean` | No tokens received yet, show initial loading state       |
| `isStreaming`  | `boolean` | Active data transmission (generation OR props streaming) |
| `isSuccess`    | `boolean` | All props completed successfully                         |
| `isError`      | `boolean` | Any fatal error occurred in generation or props          |
| `streamError?` | `Error`   | First error encountered during streaming                 |

### Per-Prop Status (`propStatus`)

Tracks individual prop streaming states:

| Field         | Type      | Description                                       |
| ------------- | --------- | ------------------------------------------------- |
| `isPending`   | `boolean` | No tokens received for this specific prop yet     |
| `isStreaming` | `boolean` | Partial content received, prop is still updating  |
| `isSuccess`   | `boolean` | Prop finished streaming successfully              |
| `error?`      | `Error`   | Error that occurred during streaming of this prop |

## Usage Patterns

### Wait for Everything to Complete

```tsx title="wait-for-all.tsx"
function ArticleCard({ title, content, author }) {
  const { streamStatus } = useTamboStreamStatus();

  if (streamStatus.isPending) return <div className="animate-pulse h-32" />;
  if (streamStatus.isError)
    return <div>Error: {streamStatus.streamError?.message}</div>;
  if (!streamStatus.isSuccess) return <Spinner />;

  return (
    <div>
      <h2>{title}</h2>
      <p>{content}</p>
      <span>By {author}</span>
    </div>
  );
}
```

### Progressive Rendering

Show each prop as it becomes available:

```tsx title="progressive-rendering.tsx"
function DashboardWidget({ title, data, config }) {
  const { propStatus } = useTamboStreamStatus();

  return (
    <div>
      {propStatus["title"]?.isPending && <div className="animate-pulse h-6" />}
      {propStatus["title"]?.isSuccess && <h3>{title}</h3>}

      {propStatus["data"]?.isStreaming && <Spinner />}
      {propStatus["data"]?.isSuccess && <DataChart data={data} />}

      {propStatus["config"]?.isSuccess && <ConfigPanel config={config} />}
    </div>
  );
}
```

### Advanced Patterns

Handle errors and group related props:

```tsx title="advanced-patterns.tsx"
function BlogPost({ title, author, content, tags }: BlogPostProps) {
  const { propStatus } = useTamboStreamStatus<BlogPostProps>();

  return (
    <article>
      {/* Group header content */}
      {propStatus["title"]?.isSuccess && propStatus["author"]?.isSuccess && (
        <header>
          <h1>{title}</h1>
          <span>By {author}</span>
        </header>
      )}

      <div>{content}</div>

      {/* Handle errors gracefully */}
      {propStatus["tags"]?.error && <p>Failed to load tags</p>}
      {propStatus["tags"]?.isSuccess && (
        <div>
          {tags.map((tag) => (
            <span key={tag}>{tag}</span>
          ))}
        </div>
      )}
    </article>
  );
}
```

## When to Use Component Streaming Status

**✅ Use When**

* Different props have different loading times
* You want progressive rendering
* You need fine-grained error handling
* You have complex UI that depends on multiple props

**❌ Don't Use When**

* You only have simple text content
* You're doing SSR/SSG (client-side only)

## Integration with Other Tambo Features

### With Stream Status Provider

```tsx title="with-provider.tsx"
import { TamboPropStreamProvider, useTamboStreamStatus } from "@tambo-ai/react";

function EnhancedComponent({ title, content, metadata }) {
  const { streamStatus } = useTamboStreamStatus();

  return (
    <TamboPropStreamProvider
      data={{ title, content, metadata }}
      streamStatus={streamStatus}
    >
      <TamboPropStreamProvider.Loading streamKey="title">
        <div className="animate-pulse h-6" />
      </TamboPropStreamProvider.Loading>

      <TamboPropStreamProvider.Complete streamKey="title">
        <h1>{title}</h1>
      </TamboPropStreamProvider.Complete>

      <TamboPropStreamProvider.Complete streamKey="content">
        <div>{content}</div>
      </TamboPropStreamProvider.Complete>
    </TamboPropStreamProvider>
  );
}
```

<Callout type="info" title="Stream Status Provider">
  The **[Stream Status
  Provider](/concepts/streaming/tambo-prop-stream-provider)** provides
  declarative streaming state management with built-in loading and complete
  states for individual props.
</Callout>

### With Streaming Props Hook

```tsx title="with-streaming-props.tsx"
import { useTamboStreamingProps, useTamboStreamStatus } from "@tambo-ai/react";

function StatefulComponent({ streamedTitle, streamedContent }) {
  const { propStatus } = useTamboStreamStatus();
  const [state, setState] = useState({ title: "", content: "" });

  useTamboStreamingProps(state, setState, {
    title: streamedTitle,
    content: streamedContent,
  });

  return (
    <div>
      <h1>{state.title}</h1>
      {propStatus["content"]?.isSuccess && <p>{state.content}</p>}
    </div>
  );
}
```

<Callout type="info" title="Streaming Props into State">
  The **[Streaming Props into State](/concepts/streaming/streaming-props)**
  feature allows you to automatically update component state as props stream in,
  providing seamless integration with React state management.
</Callout>