AI SDK UIuseCompletion

useCompletion()

Allows you to create text completion based capibilities for your application. It enables the streaming of text completions from your AI provider, manages the state for chat input, and updates the UI automatically as new messages are received.

Import

React
Svelte
Vue
Solid
import { useCompletion } from '@ai-sdk/react'

API Signature

Parameters

api:

string = '/api/completion'
The text completion API endpoint offered by the provider.

id:

string
An unique identifier for the completion. If not provided, a random one will be generated. When provided, the `useCompletion` hook with the same `id` will have shared states across components. This is useful when you have multiple components showing the same chat stream

initialInput:

string
An optional string for the initial prompt input.

initialCompletion:

string
An optional string for the initial completion result.

onResponse:

(response: Response) => void
An optional callback function that is called with the response from the API endpoint. Useful for throwing customized errors or logging.

onFinish:

(prompt: string, completion: string) => void
An optional callback function that is called when the completion stream ends.

onError:

(error: Error) => void
An optional callback that will be called when the chat stream encounters an error.

headers:

Record<string, string> | Headers
An optional object of headers to be passed to the API endpoint.

body:

any
An optional, additional body object to be passed to the API endpoint.

credentials:

'omit' | 'same-origin' | 'include'
An optional literal that sets the mode of credentials to be used on the request. Defaults to same-origin.

sendExtraMessageFields:

boolean
An optional boolean that determines whether to send extra fields you've added to `messages`. Defaults to `false` and only the `content` and `role` fields will be sent to the API endpoint.

streamMode:

'text' | 'stream-data'
An optional literal that sets the mode of the stream to be used. Defaults to `stream-data`. If set to `text`, the stream will be treated as a text stream.

Returns

completion:

string
The current text completion.

complete:

(prompt: string, options: { headers, body }) => void
Function to execute text completion based on the provided prompt.

error:

undefined | Error
The error thrown during the completion process, if any.

setCompletion:

(completion: string) => void
Function to update the `completion` state.

stop:

() => void
Function to abort the current API request.

input:

string
The current value of the input field.

setInput:

React.Dispatch<React.SetStateAction<string>>
The current value of the input field.

handleInputChange:

(event: any) => void
Handler for the `onChange` event of the input field to control the input's value.

handleSubmit:

(event: React.FormEvent<HTMLFormElement>) => void
Form submission handler that automatically resets the input field and appends a user message.

isLoading:

boolean
Boolean flag indicating whether a fetch operation is currently in progress.