useCompletion

API reference for the useCompletion hook

React hook for building text completion interfaces with AI language models.

import { useCompletion } from 'ai/react';

export default function Completion() {
  const { completion, complete, isLoading } = useCompletion();

  return (
    <div>
      <button onClick={() => complete('Write a poem about')}>
        Generate
      </button>
      {isLoading && <div>Loading...</div>}
      <div>{completion}</div>
    </div>
  );
}

Parameters

id · string

A unique identifier for the completion. If not provided, a random ID will be generated. When provided, the useCompletion hook with the same id will share states across components.

api · string · default: "/api/completion"

The API endpoint that accepts a { prompt } object and returns a stream of tokens of the completion response.

initialCompletion · string · default: "''"

Initial completion value to be used in the component.

initialInput · string · default: "''"

Initial input value to be used in the component.

credentials · RequestCredentials

The credentials mode to be used for the fetch request. Possible values are: 'omit', 'same-origin', 'include'.

headers · Record<string, string> | Headers

Additional headers to be sent with the request.

body · Record<string, unknown>

Additional body fields to be sent with the request.

streamProtocol · 'data' | 'text' · default: "'data'"

The stream protocol to use.

fetch · FetchFunction

Custom fetch implementation. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

onFinish · (prompt: string, completion: string) => void

Callback function to be called when the completion is complete.

onError · (error: Error) => void

Callback function to be called when an error occurs.

experimental_throttle · number

Custom throttle wait in milliseconds for the completion and data updates. Default is undefined, which disables throttling.

Returns

completion · string

The current completion result.

complete · (prompt: string, options?: CompletionRequestOptions) => Promise<string | null | undefined>

Send a new prompt to the API endpoint and update the completion state.

error · Error | undefined

The error object if an error occurred.

stop · () => void

Abort the current API request but keep the generated tokens.

setCompletion · (completion: string) => void

Update the completion state locally.

input · string

The current value of the input.

setInput · React.Dispatch<React.SetStateAction<string>>

setState-powered method to update the input value.

handleInputChange · (event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void

An input/textarea-ready onChange handler to control the value of the input.

handleSubmit · (event?: { preventDefault?: () => void }) => void

Form submission handler to automatically reset input and trigger completion.

isLoading · boolean

Whether the API request is in progress.

Examples

Basic completion

import { useCompletion } from 'ai/react';

export default function Completion() {
  const { completion, complete, isLoading } = useCompletion();

  return (
    <div>
      <button
        onClick={() => complete('Write a short poem about spring')}
        disabled={isLoading}
      >
        {isLoading ? 'Generating...' : 'Generate Poem'}
      </button>
      <div>{completion}</div>
    </div>
  );
}

With form input

import { useCompletion } from 'ai/react';

export default function Completion() {
  const {
    completion,
    input,
    handleInputChange,
    handleSubmit,
    isLoading,
  } = useCompletion();

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Enter a prompt..."
        />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Generating...' : 'Generate'}
        </button>
      </form>
      <div>{completion}</div>
    </div>
  );
}

With custom options

import { useCompletion } from 'ai/react';

export default function Completion() {
  const { completion, complete, isLoading } = useCompletion({
    api: '/api/custom-completion',
    onFinish: (prompt, completion) => {
      console.log('Finished:', completion);
    },
    onError: (error) => {
      console.error('Error:', error);
    },
  });

  return (
    <div>
      <button
        onClick={() =>
          complete('Write a story', {
            body: { temperature: 0.8 },
          })
        }
        disabled={isLoading}
      >
        Generate
      </button>
      <div>{completion}</div>
    </div>
  );
}

Streaming with stop

import { useCompletion } from 'ai/react';

export default function Completion() {
  const { completion, complete, stop, isLoading } = useCompletion();

  return (
    <div>
      <button onClick={() => complete('Write a long story')}>
        Start
      </button>
      <button onClick={stop} disabled={!isLoading}>
        Stop
      </button>
      <div>{completion}</div>
    </div>
  );
}