AI
AI SDK UIuseObject

experimental_useObject()

useObject is an experimental feature and only available in React.

Allows you to consume text streams that represent a JSON object and parse them into a complete object based on a schema. You can use it together with streamObject in the backend.

'use client';


import { experimental_useObject as useObject } from 'ai/react';


export default function Page() {
  const { object, submit } = useObject({
    api: '/api/use-object',
    schema: z.object({ content: z.string() }),
  });


  return (
    <div>
      <button onClick={() => submit('example input')}>Generate</button>
      {object?.content && <p>{object.content}</p>}
    </div>
  );
}

Import 

import { experimental_useObject as useObject } from 'ai/react'

API Signature

Parameters

api:

string
The API endpoint that is called to generate objects. It should stream JSON that matches the schema as chunked text. It can be a relative path (starting with `/`) or an absolute URL.

schema:

Zod Schema | JSON Schema
A schema that defines the shape of the complete object. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).

id?:

string
A unique identifier. If not provided, a random one will be generated. When provided, the `useObject` hook with the same `id` will have shared states across components.

initialValue?:

DeepPartial<RESULT> | undefined
An value for the initial object. Optional.

fetch?:

FetchFunction
A custom fetch function to be used for the API call. Defaults to the global fetch function. Optional.

headers?:

Record<string, string> | Headers
A headers object to be passed to the API endpoint. Optional.

onError?:

(error: Error) => void
Callback function to be called when an error is encountered. Optional.

onFinish?:

(result: OnFinishResult) => void
Called when the streaming response has finished.
OnFinishResult

object:

T | undefined
The generated object (typed according to the schema). Can be undefined if the final object does not match the schema.

error:

unknown | undefined
Optional error object. This is e.g. a TypeValidationError when the final object does not match the schema.

Returns

submit:

(input: INPUT) => void
Calls the API with the provided input as JSON body.

object:

DeepPartial<RESULT> | undefined
The current value for the generated object. Updated as the API streams JSON chunks.

error:

Error | unknown
The error object if the API call fails.

isLoading:

boolean
Boolean flag indicating whether a request is currently in progress.

stop:

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

Examples