Stream.Root

Stream.Root is the foundation of StreamUI. It provides context with the streaming data and state to all child primitives.

Demo

Idle

Rendered UI

location:

temperature:

condition:

Context State

location:

temperature:

condition:

state:idle

Usage

import { Stream } from "@stream.ui/react";
import { experimental_useObject as useObject } from "@ai-sdk/react";

function ArticleCard() {
  const { object, isLoading, error } = useObject({
    api: "/api/article",
    schema: articleSchema,
  });

  return (
    <Stream.Root data={object} isLoading={isLoading} error={error}>
      <div className="rounded-2xl border bg-card p-6">
        <Stream.Field fallback={<Skeleton className="h-6 w-32" />}>
          <h3 className="text-lg font-semibold">{object?.title}</h3>
        </Stream.Field>
        
        <Stream.Field fallback={<Skeleton className="h-12 w-20" />}>
          <p className="text-muted-foreground">{object?.summary}</p>
        </Stream.Field>
        
        <Stream.When streaming>
          <div className="absolute top-3 right-3">
            <div className="h-2 w-2 rounded-full bg-blue-500 animate-pulse" />
          </div>
        </Stream.When>
      </div>
    </Stream.Root>
  );
}

Anatomy

import { Stream } from "@stream.ui/react";

<Stream.Root data={object} isLoading={isLoading} error={error}>
  {/* Stream.Field, Stream.List, Stream.When go here */}
</Stream.Root>

How It Works

Stream.Root creates a React context that all child primitives can access:

Pass data, isLoading, and error from your streaming hook (e.g., useObject)
The component derives the current state from these props
Child components (Stream.Field, Stream.List, Stream.When) read this context to behave accordingly

States

Stream.Root derives the current state from its props:

State	Condition
`idle`	`!isLoading && !data && !error`
`loading`	`isLoading && !data`
`streaming`	`isLoading && data`
`complete`	`!isLoading && data`
`error`	`error` exists

API Reference

Props

Prop	Type	Default
`data`	`DeepPartial<T> \| undefined`	—
`isLoading`	`boolean`	`false`
`error`	`Error \| undefined`	—
`children`	`ReactNode`	—

Context Value

Property	Type
`data`	`DeepPartial<T> \| undefined`
`state`	`StreamState`
`isLoading`	`boolean`
`isStreaming`	`boolean`
`isComplete`	`boolean`
`error`	`Error \| undefined`

Stream.Root

On this page