Show streamed completion output as it arrives
Live generated text
AI Tools · Hook
useCompletion
useCompletion is a React hook for text-completion interfaces. It streams provider output, manages completion state, and exposes complete for starting generation.
How it works
useCompletion provides a completion value and an imperative complete function for generating text from a prompt. It calls a configurable endpoint, streams the provider's response into the completion state, and can share state between components when they use the same identifier.
Syntax
const { completion, complete } = useCompletion({ api?: string, id?: string })Parameters
| Name | Type | Description |
|---|---|---|
api | string = '/api/completion' | API endpoint used to generate text; defaults to /api/completion and accepts a relative path or absolute URL. |
id | string | Unique completion identifier; matching identifiers allow hook instances to share state, while omission generates one randomly. |
BODY | object | Type parameter for additional request-body data passed through hook options or complete. |
complete | (prompt: string, options?: { headers?: Record<string, string> | Headers, body?: BODY }) => Promise<string | null | undefined> | Prompt and optional headers or body used to execute a completion request. |
Returns
An object including completion, the complete function, and hook-managed completion UI state such as loading and error state.
Key points
- Import the React hook from @ai-sdk/react.
- Use the hook to build interfaces centered on text completion.
- Provider output can be displayed incrementally rather than waiting for the entire response.
- The hook manages input-related state and refreshes the rendered interface as streamed content arrives.
- completion contains the current generated text.
- complete accepts a prompt and optional headers or request body, then initiates generation.
- The complete promise resolves with the resulting completion after generation finishes.
Common mistakes
- Without an id, each hook instance receives a generated identifier; supply the same id when components must share completion state.
- The api option must be either a relative path beginning with / or an absolute URL.
Example: Stream a completion in React
import { useCompletion } from '@ai-sdk/react'
export default function Page() {
const { completion, complete } = useCompletion({
api: '/api/completion',
})
return (
<div>
<button onClick={() => complete('Why is the sky blue?')}>
Generate
</button>
<pre>{completion}</pre>
</div>
)
}A React component sends a prompt to the completion endpoint and renders the streamed completion.
When to use it
Coordinate completion state across components with a common id
Shared interface state
Send prompts to a relative or absolute completion endpoint
Custom backend routing
Interview questions
QWhat does useCompletion provide, and how is generation started?
The hook exposes completion state and a complete function. Calling complete with a prompt sends the request and returns a promise that resolves to the completion result when generation finishes.
Follow-up: How can two components share the same completion state? Configure both hook instances with the same id, because that identifier links their state.
QHow does useCompletion choose the server endpoint?
api selects the endpoint used to generate text, and it defaults to /api/completion. The endpoint may be expressed as a relative path or an absolute URL.
Follow-up: How would you pass request-specific data? Provide a body through the complete function's options or through the hook configuration's supported request options.
QHow does the hook update the interface during generation?
The hook streams text completions from the AI provider and updates the UI as new completion text arrives. The current generated text is available through completion.
Follow-up: Which stream formats are supported? The documentation identifies text and data stream parts for useCompletion.
Related
useChatuseObjectTextStreamChatTransportstreamProtocol