component-rendering

コンポーネントのレンダリング

ストリーミング中のプロパティと永続的なコンポーネント状態を処理します。

クイックスタート

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

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

ストリームのステータス

全体およびプロパティごとのストリーミング状態を追跡します。

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 のプロパティ

プロパティ	説明
isPending	まだトークンを受信していません
isStreaming	ストリーミング中です
isSuccess	すべてのプロパティがエラーなく完了しました
isError	致命的なエラーが発生しました
streamError	失敗した場合のエラーオブジェクト

PropStatus（プロパティごと）

プロパティ	説明
isPending	このプロパティのトークンをまだ受信していません
isStreaming	プロパティに部分的なコンテンツがあります
isSuccess	プロパティのストリーミングが完了しました
error	このプロパティのエラー（ある場合）

コンポーネントの状態

AI が状態を確認できるようにし、セッションをまたいで保持します。

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)
);

戻り値	説明
value	現在の状態値
setValue	状態を更新します（更新関数にも対応）
meta.isPending	サーバーとの同期中
meta.error	同期エラー（ある場合）
meta.flush	保留中のデバウンスされた更新を直ちに反映します

setValue のパターン

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

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

コンポーネントの状態を使用する場面

• AI に把握させる、ユーザーが編集できるコンテンツ
• 永続化が必要なフォーム入力
• ページを再読み込みしても保持される状態
• 生成後にユーザーが変更できるストリーミング中のプロパティ

ストリーミングのベストプラクティス

1. Zod スキーマでプロパティを省略可能にする：

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

2. データがない場合はエラーではなく、スケルトンを表示する

3. オプショナルチェーンを使用する：items?.map(...)

4. streamStatus.isSuccess になるまで、操作を無効にする