What is useTamboStreamStatus?

A hook to track global and per-prop streaming status, exposing isPending, isStreaming, isSuccess, isError, and streamError, plus per-prop statuses.

How do I persist component state across sessions?

Use useTamboComponentState with a key and initial value; it returns value, setValue, and meta including isPending, error, and flush to push debounced updates.

When should I show skeletons vs loading indicators?

Show skeletons for isPending or missing data, and use loading indicators for isStreaming to reflect active data arrival without misrepresenting errors.

component-rendering

npx machina-cli add skill andrmaz/spec-driven-architecture/component-rendering --openclaw

Files (1)

SKILL.md

3.8 KB

Component Rendering

Handles streaming props and persistent component state.

Quick Start

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

if (streamStatus.isPending) return <Skeleton />;
if (streamStatus.isStreaming) return <LoadingIndicator />;

Stream Status

Track overall and per-prop streaming status:

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

function MyComponent({ title, items }: Props) {
  const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

  // Global status
  if (streamStatus.isPending) return <Skeleton />;
  if (streamStatus.isStreaming) return <LoadingIndicator />;
  if (streamStatus.isError) return <Error message={streamStatus.streamError} />;

  // Per-prop status
  return (
    <h2 className={propStatus.title?.isStreaming ? "animate-pulse" : ""}>
      {title}
    </h2>
  );
}

StreamStatus Properties

Property	Description
`isPending`	No tokens received yet
`isStreaming`	Active streaming in progress
`isSuccess`	All props finished without error
`isError`	Fatal error occurred
`streamError`	Error object if failed

PropStatus (per-prop)

Property	Description
`isPending`	No tokens for this prop yet
`isStreaming`	Prop has partial content
`isSuccess`	Prop finished streaming
`error`	Error for this prop (if any)

Component State

Make state visible to AI and persist across sessions:

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

function EditableCard({ title: streamedTitle }: { title?: string }) {
  const [title, setTitle, { isPending, flush }] = useTamboComponentState(
    "title",
    "",
  );
  const { streamStatus } = useTamboStreamStatus();

  return (
    <input
      value={title}
      onChange={(e) => setTitle(e.target.value)}
      disabled={streamStatus.isStreaming || isPending}
    />
  );
}

useTamboComponentState API

const [value, setValue, meta] = useTamboComponentState(
  key, // Unique state key within the component
  initialValue, // Initial value if no server state
  debounceTime, // Debounce ms (default: 500)
);

Return	Description
`value`	Current state value
`setValue`	Update state (supports updater functions)
`meta.isPending`	Server sync in progress
`meta.error`	Sync error (if any)
`meta.flush`	Immediately flush pending debounced updates

setValue Patterns

// Direct value
setTitle("New title");

// Updater function
setCount((prev) => prev + 1);

When to Use Component State

User-editable content AI should see
Form inputs requiring persistence
State that survives page reloads
Streaming props that user can modify after generation

Streaming Best Practices

Make props optional in Zod schema:

z.object({
  title: z.string().optional().describe("Card title"),
  items: z.array(z.string()).optional(),
});

Show skeletons for missing data, not errors
Use optional chaining: items?.map(...)
Disable interactions until streamStatus.isSuccess

Source

git clone https://github.com/andrmaz/spec-driven-architecture/blob/develop/.agents/skills/component-rendering/SKILL.mdView on GitHub

Overview

Component Rendering manages streaming props and persistent component state for Tambo-based UIs. It exposes streamStatus and per-prop propStatus to render skeletons, loading indicators, and styled content while data streams in, and it supports persisting state across sessions with useTamboStreamStatus and useTamboComponentState.

How This Skill Works

Use useTamboStreamStatus to monitor global and per-prop streaming status, allowing conditional UI like Skeleton or LoadingIndicator. Use useTamboComponentState to persist component state across sessions, receiving value, setValue, and meta (including isPending, error, and flush) for debounced updates.

When to Use It

Building a card with a title and items where data streams progressively
Tracking per-prop streaming status to apply UI cues (e.g., animated title while streaming)
Managing partial props during incremental rendering
Persisting component state across page reloads or sessions
Creating editable UI that remains in sync while data streams in

Quick Start

Step 1: Import hooks, e.g. import { useTamboStreamStatus, useTamboComponentState } from '@tambo-ai/react';
Step 2: Use useTamboStreamStatus to read global and per-prop status and render Skeleton or LoadingIndicator accordingly
Step 3: Use useTamboComponentState for persistent fields (e.g., title) and wire setValue to inputs

Best Practices

Make props optional in your schema to tolerate missing tokens during streaming
Show skeletons for missing data rather than rendering errors
Use optional chaining (e.g., items?.map(...)) to safely render partial data
Disable interactions until streamStatus.isSuccess for a consistent UX
Leverage the meta.flush mechanism to push debounced updates when needed

Example Use Cases

EditableCard where title updates as the stream provides partial props but remains editable
Product list widget showing skeletons until title and items arrive, then full rendering
Form that persists user input across sessions using useTamboComponentState
Dashboard widget that transitions from skeleton to loading indicator as data streams
Chat-like feed where messages stream in progressively and UI reflects partial props

Frequently Asked Questions

Add this skill to your agents