Progressive server-rendered results
A server action returns loading UI immediately and later replaces it with fetched data.
AI Tools · Function
createStreamableUI
Creates a server-to-client stream for React UI. The client can render its value as a normal React node while the server updates, appends, finalizes, or fails the stream.
How it works
Call createStreamableUI with an optional initial React node to obtain a streamable UI handle. Update replaces the current node, append adds a node permanently, done closes the stream with its final node, and error propagates a failure to the client; return value is the React node that a Server Action can send to the client.
Syntax
createStreamableUI(initialValue?: ReactNode)Parameters
| Name | Type | Description |
|---|---|---|
initialValue | ReactNode | Optional initial React node used as the stream's starting value. |
Returns
An object containing value, the ReactNode stream that can be returned from a Server Action and received by the client, plus update, append, done, and error methods.
Key points
- The function creates a server-to-client stream for UI.
- The received stream value renders as an ordinary React node.
- An optional initial ReactNode establishes the stream's starting UI.
- update replaces the currently displayed node with a new one.
- append adds new UI after the existing node.
- error reports a stream failure that is thrown on the client.
Common mistakes
- After append, the earlier UI node is immutable and cannot be updated.
- Calling done permanently closes the stream, so no later update or append is valid.
- Always call done; omitting it leaves the client waiting indefinitely.
Example: Stream a loading state and final UI
import { createStreamableUI } from '@ai-sdk/rsc';
export async function getWeather() {
const ui = createStreamableUI(<p>Loading…</p>);
setTimeout(() => ui.done(<p>Sunny, 22°C</p>), 1000);
return ui.value;
}Creates server-side UI with an initial loading node, finalizes it later, and returns the stream value for the client.
When to use it
UI during tool execution
A tool call needs to display a React component during model generation.
Appending a UI sequence
A server produces multiple sequential UI nodes that should remain visible.
Interview questions
QWhat does createStreamableUI provide?
It creates a stream containing a React UI node that can be rendered on the client. The primitive itself does not invoke a language model; it gives the server explicit control over UI streaming.
Follow-up: How would you expose the streamed UI? Return the handle's value from a Server Action so the client can receive and render that React node.
QHow do update and append differ?
update replaces the current UI node, while append adds another node after the existing content. After append, the earlier node can no longer be changed.
Follow-up: When should append be avoided? Avoid it when the existing streamed node must continue changing; use update until the content is ready to finalize.
QHow should a stream be terminated?
done finalizes the stream and may receive a final React node or null. It must be called because otherwise the response remains in a loading state; error instead signals a client-side failure handled by the nearest error boundary.
Follow-up: What happens after done? The stream cannot be updated or appended, so all intended final UI must be supplied before or during that call.
Related
createStreamableValuecreateAIstreamUI